@google-cloud/pubsub 2.16.6 → 2.18.2

package/build/src/topic.js

@@ -17,9 +17,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Topic = void 0;
 const paginator_1 = require("@google-cloud/paginator");
-const promisify_1 = require("@google-cloud/promisify");
 const iam_1 = require("./iam");
 const publisher_1 = require("./publisher");
+const flow_publisher_1 = require("./publisher/flow-publisher");
+const util_1 = require("./util");
 /**
  * A Topic object allows you to interact with a Cloud Pub/Sub topic.
  *
@@ -29,13 +30,17 @@ const publisher_1 = require("./publisher");
  * @param {PublishOptions} [options] Publisher configuration object.
  *
  * @example
+ * ```
  * const {PubSub} = require('@google-cloud/pubsub');
  * const pubsub = new PubSub();
  *
  * const topic = pubsub.topic('my-topic');
  *
- * @example <caption>To enable message ordering, set `enableMessageOrdering` to true. Please note that this does not persist to an actual topic.</caption>
+ * ```
+ * @example To enable message ordering, set `enableMessageOrdering` to true. Please note that this does not persist to an actual topic.
+ * ```
  * const topic = pubsub.topic('ordered-topic', {enableMessageOrdering: true});
+ * ```
  */
 class Topic {
     constructor(pubsub, name, options) {
@@ -80,6 +85,7 @@ class Topic {
          * @see [What is Cloud IAM?]{@link https://cloud.google.com/iam/}
          *
          * @example
+         * ```
          * const {PubSub} = require('@google-cloud/pubsub');
          * const pubsub = new PubSub();
          *
@@ -99,124 +105,25 @@ class Topic {
          *   const policy = data[0];
          *   const apiResponse = data[1];
          * });
+         * ```
          */
         this.iam = new iam_1.IAM(pubsub, this.name);
     }
-    /**
-     * Immediately sends all remaining queued data. This is mostly useful
-     * if you are planning to call close() on the PubSub object that holds
-     * the server connections.
-     *
-     * @param {EmptyCallback} [callback] Callback function.
-     * @returns {Promise<EmptyResponse>}
-     */
     flush(callback) {
         // It doesn't matter here if callback is undefined; the Publisher
         // flush() will handle it.
         this.publisher.flush(callback);
     }
-    /**
-     * Create a topic.
-     *
-     * @param {object} [gaxOpts] Request configuration options, outlined
-     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
-     * @param {CreateTopicCallback} [callback] Callback function.
-     * @returns {Promise<CreateTopicResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     *
-     * topic.create((err, topic, apiResponse) => {
-     *   if (!err) {
-     *     // The topic was created successfully.
-     *   }
-     * });
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.create().then((data) => {
-     *   const topic = data[0];
-     *   const apiResponse = data[1];
-     * });
-     */
     create(optsOrCallback, callback) {
         const gaxOpts = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
         this.pubsub.createTopic(this.name, gaxOpts, callback);
     }
-    /**
-     * Create a subscription to this topic.
-     *
-     * @see [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create}
-     *
-     * @throws {Error} If subscription name is omitted.
-     *
-     * @param {string} name The name of the subscription.
-     * @param {CreateSubscriptionRequest} [options] See a
-     *     [Subscription
-     * resource](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions).
-     * @param {CreateSubscriptionCallback} [callback] Callback function.
-     * @returns {Promise<CreateSubscriptionResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     * const callback = function(err, subscription, apiResponse) {};
-     *
-     * // Without specifying any options.
-     * topic.createSubscription('newMessages', callback);
-     *
-     * // With options.
-     * topic.createSubscription('newMessages', {
-     *   ackDeadlineSeconds: 90
-     * }, callback);
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.createSubscription('newMessages').then((data) => {
-     *   const subscription = data[0];
-     *   const apiResponse = data[1];
-     * });
-     */
     createSubscription(name, optsOrCallback, callback) {
         const options = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
         this.pubsub.createSubscription(this, name, options, callback);
     }
-    /**
-     * Delete the topic. This will not delete subscriptions to this topic.
-     *
-     * @see [Topics: delete API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/delete}
-     *
-     * @param {object} [gaxOpts] Request configuration options, outlined
-     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
-     * @param {function} [callback] The callback function.
-     * @param {?error} callback.err An error returned while making this
-     *     request.
-     * @param {object} callback.apiResponse Raw API response.
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     *
-     * topic.delete((err, apiResponse) => {});
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.delete().then((data) => {
-     *   const apiResponse = data[0];
-     * });
-     */
     delete(optsOrCallback, callback) {
         const gaxOpts = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
@@ -230,36 +137,6 @@ class Topic {
             gaxOpts: gaxOpts,
         }, callback);
     }
-    /**
-     * @typedef {array} TopicExistsResponse
-     * @property {boolean} 0 Whether the topic exists
-     */
-    /**
-     * @callback TopicExistsCallback
-     * @param {?Error} err Request error, if any.
-     * @param {boolean} exists Whether the topic exists.
-     */
-    /**
-     * Check if a topic exists.
-     *
-     * @param {TopicExistsCallback} [callback] Callback function.
-     * @returns {Promise<TopicExistsResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     *
-     * topic.exists((err, exists) => {});
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.exists().then((data) => {
-     *   const exists = data[0];
-     * });
-     */
     exists(callback) {
         this.getMetadata(err => {
             if (!err) {
@@ -273,45 +150,6 @@ class Topic {
             callback(err);
         });
     }
-    /**
-     * @typedef {array} GetTopicResponse
-     * @property {Topic} 0 The {@link Topic}.
-     * @property {object} 1 The full API response.
-     */
-    /**
-     * @callback GetTopicCallback
-     * @param {?Error} err Request error, if any.
-     * @param {Topic} topic The {@link Topic}.
-     * @param {object} apiResponse The full API response.
-     */
-    /**
-     * Get a topic if it exists.
-     *
-     * @param {object} [gaxOpts] Request configuration options, outlined
-     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
-     * @param {boolean} [gaxOpts.autoCreate=false] Automatically create the topic
-     *     does not already exist.
-     * @param {GetTopicCallback} [callback] Callback function.
-     * @returns {Promise<GetTopicResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     *
-     * topic.get((err, topic, apiResponse) => {
-     *   // The `topic` data has been populated.
-     * });
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.get().then((data) => {
-     *   const topic = data[0];
-     *   const apiResponse = data[1];
-     * });
-     */
     get(optsOrCallback, callback) {
         const gaxOpts = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
@@ -329,40 +167,6 @@ class Topic {
             this.create(gaxOpts, callback);
         });
     }
-    /**
-     * @typedef {array} GetTopicMetadataResponse
-     * @property {object} 0 The full API response.
-     */
-    /**
-     * @callback GetTopicMetadataCallback
-     * @param {?Error} err Request error, if any.
-     * @param {object} apiResponse The full API response.
-     */
-    /**
-     * Get the official representation of this topic from the API.
-     *
-     * @see [Topics: get API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/get}
-     *
-     * @param {object} [gaxOpts] Request configuration options, outlined
-     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
-     * @param {GetTopicMetadataCallback} [callback] Callback function.
-     * @returns {Promise<GetTopicMetadataResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     *
-     * topic.getMetadata((err, apiResponse) => {});
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.getMetadata().then((data) => {
-     *   const apiResponse = data[0];
-     * });
-     */
     getMetadata(optsOrCallback, callback) {
         const gaxOpts = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
@@ -381,42 +185,6 @@ class Topic {
             callback(err, apiResponse);
         });
     }
-    /**
-     * Get a list of the subscriptions registered to this topic. You may
-     * optionally provide a query object as the first argument to customize the
-     * response.
-     *
-     * Your provided callback will be invoked with an error object if an API error
-     * occurred or an array of {module:pubsub/subscription} objects.
-     *
-     * @see [Subscriptions: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics.subscriptions/list}
-     *
-     * @param {GetSubscriptionsRequest} [query] Query object for listing subscriptions.
-     * @param {GetSubscriptionsCallback} [callback] Callback function.
-     * @returns {Promise<GetSubscriptionsResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     *
-     * topic.getSubscriptions((err, subscriptions) => {
-     *   // subscriptions is an array of `Subscription` objects.
-     * });
-     *
-     * // Customize the query.
-     * topic.getSubscriptions({
-     *   pageSize: 3
-     * }, callback);
-     *
-     * //-
-     * // If the callback is omitted, we'll return a Promise.
-     * //-
-     * topic.getSubscriptions().then((data) => {
-     *   const subscriptions = data[0];
-     * });
-     */
     getSubscriptions(optsOrCallback, callback) {
         const options = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
@@ -441,93 +209,11 @@ class Topic {
             callback(err, subscriptions, ...args);
         });
     }
-    /**
-     * Publish the provided message.
-     *
-     * @deprecated Please use {@link Topic#publishMessage}.
-     *
-     * @throws {TypeError} If data is not a Buffer object.
-     * @throws {TypeError} If any value in `attributes` object is not a string.
-     *
-     * @param {buffer} data The message data. This must come in the form of a
-     *     Buffer object.
-     * @param {object.<string, string>} [attributes] Attributes for this message.
-     * @param {PublishCallback} [callback] Callback function.
-     * @returns {Promise<PublishResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     * const data = Buffer.from('Hello, world!');
-     *
-     * const callback = (err, messageId) => {
-     *   if (err) {
-     *     // Error handling omitted.
-     *   }
-     * };
-     *
-     * topic.publish(data, callback);
-     *
-     * @example <caption>Optionally you can provide an object containing attributes for the message. Note that all values in the object must be strings.</caption>
-     * const attributes = {
-     *   key: 'value'
-     * };
-     *
-     * topic.publish(data, attributes, callback);
-     *
-     * @example <caption>If the callback is omitted, we'll return a Promise.</caption>
-     * topic.publish(data).then((messageId) => {});
-     */
     publish(data, attrsOrCb, callback) {
         const attributes = typeof attrsOrCb === 'object' ? attrsOrCb : {};
         callback = typeof attrsOrCb === 'function' ? attrsOrCb : callback;
         return this.publishMessage({ data, attributes }, callback);
     }
-    /**
-     * Publish the provided JSON. It should be noted that all messages published
-     * are done so in the form of a Buffer. This is simply a convenience method
-     * that will transform JSON into a Buffer before publishing.
-     * {@link Subscription} objects will always return message data in the form of
-     * a Buffer, so any JSON published will require manual deserialization.
-     *
-     * @deprecated Please use the `json` option via {@link Topic#publishMessage}.
-     *
-     * @throws {Error} If non-object data is provided.
-     *
-     * @param {object} json The JSON data to publish.
-     * @param {object} [attributes] Attributes for this message.
-     * @param {PublishCallback} [callback] Callback function.
-     * @returns {Promise<PublishResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     * const topic = pubsub.topic('my-topic');
-     *
-     * const data = {
-     *   foo: 'bar'
-     * };
-     *
-     * const callback = (err, messageId) => {
-     *   if (err) {
-     *     // Error handling omitted.
-     *   }
-     * };
-     *
-     * topic.publishJSON(data, callback);
-     *
-     * @example <caption>Optionally you can provide an object containing attributes for the message. Note that all values in the object must be strings.</caption>
-     * const attributes = {
-     *   key: 'value'
-     * };
-     *
-     * topic.publishJSON(data, attributes, callback);
-     *
-     * @example <caption>If the callback is omitted, we'll return a Promise.</caption>
-     * topic.publishJSON(data).then((messageId) => {});
-     */
     publishJSON(json, attrsOrCb, callback) {
         if (!json || typeof json !== 'object') {
             throw new Error('First parameter should be an object.');
@@ -536,58 +222,9 @@ class Topic {
         callback = typeof attrsOrCb === 'function' ? attrsOrCb : callback;
         return this.publishMessage({ json, attributes }, callback);
     }
-    /**
-     * @typedef {object} MessageOptions
-     * @property {buffer} [data] The message data.
-     * @property {object} [json] Convenience property to publish JSON data. This
-     *     will transform the provided JSON into a Buffer before publishing.
-     *     {@link Subscription} objects will always return message data in the
-     *     form of a Buffer, so any JSON published will require manual
-     *     deserialization.
-     * @property {object.<string, string>} [attributes] Attributes for this
-     *     message.
-     * @property {string} [orderingKey] A message ordering key.
-     */
-    /**
-     * Publish the provided message.
-     *
-     * @throws {TypeError} If data is not a Buffer object.
-     * @throws {TypeError} If any value in `attributes` object is not a string.
-     *
-     * @param {MessageOptions} message Message object.
-     * @param {PublishCallback} [callback] Callback function.
-     * @returns {Promise<PublishResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     * const topic = pubsub.topic('my-topic');
-     *
-     * const data = Buffer.from('Hello, world!');
-     *
-     * const callback = (err, messageId) => {
-     *   if (err) {
-     *     // Error handling omitted.
-     *   }
-     * };
-     *
-     * topic.publishMessage({data}, callback);
-     *
-     * @example <caption>Publish JSON message data.</caption>
-     * const json = {foo: 'bar'};
-     *
-     * topic.publishMessage({json}, callback);
-     *
-     * @example <caption>To publish messages in order (this is still experimental), make sure message ordering is enabled and provide an ordering key</caption>
-     * const topic = pubsub.topic('ordered-topic', {messageOrdering: true});
-     * const orderingKey = 'my-key';
-     *
-     * topic.publishMessage({data, orderingKey}, callback);
-     *
-     * @example <caption>If the callback is omitted, we'll return a Promise.</caption>
-     * const [messageId] = await topic.publishMessage({data});
-     */
     publishMessage(message, callback) {
+        // Make a copy to ensure that any changes we make to it will not
+        // propagate up to the user's data.
         message = Object.assign({}, message);
         if (message.json && typeof message.json === 'object') {
             message.data = Buffer.from(JSON.stringify(message.json));
@@ -595,6 +232,22 @@ class Topic {
         }
         return this.publisher.publishMessage(message, callback);
     }
+    /**
+     * Creates a FlowControlledPublisher for this Topic.
+     *
+     * FlowControlledPublisher is a helper that lets you control how many messages
+     * are simultaneously queued to send, to avoid ballooning memory usage on
+     * a low bandwidth connection to Pub/Sub.
+     *
+     * Note that it's perfectly fine to create more than one on the same Topic.
+     * The actual flow control settings on the Topic will apply across all
+     * FlowControlledPublisher objects on that Topic.
+     *
+     * @returns {FlowControlledPublisher} The flow control helper.
+     */
+    flowControlled() {
+        return new flow_publisher_1.FlowControlledPublisher(this.publisher);
+    }
     /**
      * In the event that the client fails to publish an ordered message, all
      * subsequent publish calls using the same ordering key will fail. Calling
@@ -604,6 +257,7 @@ class Topic {
      * @param {string} orderingKey The ordering key in question.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      * const topic = pubsub.topic('my-topic', {messageOrdering: true});
@@ -616,54 +270,11 @@ class Topic {
      *     topic.resumePublishing(orderingKey);
      *   }
      * });
+     * ```
      */
     resumePublishing(orderingKey) {
         this.publisher.resumePublishing(orderingKey);
     }
-    /**
-     * @typedef {array} SetTopicMetadataResponse
-     * @property {object} 0 The full API response.
-     */
-    /**
-     * @callback SetTopicMetadataCallback
-     * @param {?Error} err Request error, if any.
-     * @param {object} apiResponse The full API response.
-     */
-    /**
-     * Updates the topic.
-     *
-     * @see [UpdateTopicRequest API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#google.pubsub.v1.UpdateTopicRequest}
-     *
-     * @param {object} metadata The fields to update. This should be structured
-     *     like a {@link
-     * https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#Topic|Topic
-     * object}.
-     * @param {object} [gaxOpts] Request configuration options, outlined
-     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
-     * @param {SetTopicMetadataCallback} [callback] Callback function.
-     * @returns {Promise<SetTopicMetadataResponse>}
-     *
-     * @example
-     * const {PubSub} = require('@google-cloud/pubsub');
-     * const pubsub = new PubSub();
-     *
-     * const topic = pubsub.topic('my-topic');
-     * const metadata = {
-     *   labels: {foo: 'bar'}
-     * };
-     *
-     * topic.setMetadata(metadata, err => {
-     *   if (err) {
-     *     // Error handling omitted.
-     *   }
-     * });
-     *
-     * @example <caption>If the callback is omitted, we'll return a
-     * Promise.</caption>
-     * topic.setMetadata(metadata).then((data) => {
-     *   const apiResponse = data[0];
-     * });
-     */
     setMetadata(options, optsOrCallback, callback) {
         const gaxOpts = typeof optsOrCallback === 'object' ? optsOrCallback : {};
         callback = typeof optsOrCallback === 'function' ? optsOrCallback : callback;
@@ -683,6 +294,7 @@ class Topic {
      * @param {PublishOptions} options The publisher options.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
@@ -693,6 +305,7 @@ class Topic {
      *     maxMilliseconds: 10
      *   }
      * });
+     * ```
      */
     setPublishOptions(options) {
         this.publisher.setOptions(options);
@@ -702,6 +315,7 @@ class Topic {
      * back into {@link Topic#setPublishOptions}.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
@@ -710,6 +324,7 @@ class Topic {
      * const defaults = topic.getPublishOptionDefaults();
      * defaults.batching.maxMilliseconds = 10;
      * topic.setPublishOptions(defaults);
+     * ```
      */
     getPublishOptionDefaults() {
         // Generally I'd leave this as a static, but it'll be easier for users to
@@ -728,6 +343,7 @@ class Topic {
      * @return {Subscription}
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
@@ -743,6 +359,7 @@ class Topic {
      *   // message.attributes = Attributes of the message.
      *   // message.publishTime = Timestamp when Pub/Sub received the message.
      * });
+     * ```
      */
     subscription(name, options) {
         options = options || {};
@@ -776,6 +393,7 @@ exports.Topic = Topic;
  * @returns {ReadableStream} A readable stream of {@link Subscription} instances.
  *
  * @example
+ * ```
  * const {PubSub} = require('@google-cloud/pubsub');
  * const pubsub = new PubSub();
  *
@@ -798,6 +416,7 @@ exports.Topic = Topic;
  *   .on('data', function(subscription) {
  *     this.end();
  *   });
+ * ```
  */
 /*! Developer Documentation
  *
@@ -806,17 +425,19 @@ exports.Topic = Topic;
 paginator_1.paginator.extend(Topic, ['getSubscriptions']);
 /*! Developer Documentation
  *
- * All async methods (except for streams) will return a Promise in the event
- * that a callback is omitted.
+ * Existing async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted. Future methods will not allow for a callback.
+ * (Use .then() on the returned Promise instead.)
  */
-promisify_1.promisifyAll(Topic, {
-    exclude: [
-        'publish',
-        'publishJSON',
-        'publishMessage',
-        'setPublishOptions',
-        'getPublishOptionDefaults',
-        'subscription',
-    ],
-});
+util_1.promisifySome(Topic, Topic.prototype, [
+    'flush',
+    'create',
+    'createSubscription',
+    'delete',
+    'exists',
+    'get',
+    'getMetadata',
+    'getSubscriptions',
+    'setMetadata',
+]);
 //# sourceMappingURL=topic.js.map