diff --git a/packages/google-cloud-asset/package.json b/packages/google-cloud-asset/package.json index 71e7d2be20c..4566e70233e 100644 --- a/packages/google-cloud-asset/package.json +++ b/packages/google-cloud-asset/package.json @@ -46,7 +46,7 @@ "api-documenter": "api-documenter yaml --input-folder=temp" }, "dependencies": { - "google-gax": "^2.1.0" + "google-gax": "^2.9.2" }, "devDependencies": { "@types/mocha": "^8.0.0", diff --git a/packages/google-cloud-asset/src/v1/asset_service_client.ts b/packages/google-cloud-asset/src/v1/asset_service_client.ts index edbb4fb0f80..04c7dca517a 100644 --- a/packages/google-cloud-asset/src/v1/asset_service_client.ts +++ b/packages/google-cloud-asset/src/v1/asset_service_client.ts @@ -62,8 +62,10 @@ export class AssetServiceClient { /** * Construct an instance of AssetServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @param {object} [options] - The configuration object. + * The options accepted by the constructor are described in detail + * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance). + * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] @@ -83,42 +85,33 @@ export class AssetServiceClient { * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. + * @param {gax.ClientConfig} [options.clientConfig] - client configuration override. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AssetServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); - if (!opts) { - opts = {servicePath, port}; + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AssetServiceClient constructor. + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AssetServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -127,6 +120,11 @@ export class AssetServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -325,6 +323,7 @@ export class AssetServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'cloudasset.googleapis.com'; @@ -333,6 +332,7 @@ export class AssetServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'cloudasset.googleapis.com'; @@ -340,6 +340,7 @@ export class AssetServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -348,6 +349,7 @@ export class AssetServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return ['https://www.googleapis.com/auth/cloud-platform']; @@ -357,8 +359,7 @@ export class AssetServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -441,7 +442,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [BatchGetAssetsHistoryResponse]{@link google.cloud.asset.v1.BatchGetAssetsHistoryResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.batchGetAssetsHistory(request); */ batchGetAssetsHistory( request: protos.google.cloud.asset.v1.IBatchGetAssetsHistoryRequest, @@ -539,7 +544,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Feed]{@link google.cloud.asset.v1.Feed}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createFeed(request); */ createFeed( request: protos.google.cloud.asset.v1.ICreateFeedRequest, @@ -622,7 +631,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Feed]{@link google.cloud.asset.v1.Feed}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getFeed(request); */ getFeed( request: protos.google.cloud.asset.v1.IGetFeedRequest, @@ -704,7 +717,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [ListFeedsResponse]{@link google.cloud.asset.v1.ListFeedsResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.listFeeds(request); */ listFeeds( request: protos.google.cloud.asset.v1.IListFeedsRequest, @@ -792,7 +809,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Feed]{@link google.cloud.asset.v1.Feed}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateFeed(request); */ updateFeed( request: protos.google.cloud.asset.v1.IUpdateFeedRequest, @@ -875,7 +896,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteFeed(request); */ deleteFeed( request: protos.google.cloud.asset.v1.IDeleteFeedRequest, @@ -967,7 +992,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [AnalyzeIamPolicyResponse]{@link google.cloud.asset.v1.AnalyzeIamPolicyResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.analyzeIamPolicy(request); */ analyzeIamPolicy( request: protos.google.cloud.asset.v1.IAnalyzeIamPolicyRequest, @@ -1100,8 +1129,15 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. - * The first element of the array is an object representing [Operation]{@link google.longrunning.Operation}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const [operation] = await client.exportAssets(request); + * const [response] = await operation.promise(); */ exportAssets( request: protos.google.cloud.asset.v1.IExportAssetsRequest, @@ -1153,18 +1189,19 @@ export class AssetServiceClient { return this.innerApiCalls.exportAssets(request, options, callback); } /** - * Check the status of the long running operation returned by the exportAssets() method. + * Check the status of the long running operation returned by `exportAssets()`. * @param {String} name * The operation name that will be passed. * @returns {Promise} - The promise which resolves to an object. * The decoded operation object has result and metadata field to get information from. - * - * @example: - * const decodedOperation = await checkExportAssetsProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); - * + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const decodedOperation = await checkExportAssetsProgress(name); + * console.log(decodedOperation.result); + * console.log(decodedOperation.done); + * console.log(decodedOperation.metadata); */ async checkExportAssetsProgress( name: string @@ -1244,8 +1281,15 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. - * The first element of the array is an object representing [Operation]{@link google.longrunning.Operation}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const [operation] = await client.analyzeIamPolicyLongrunning(request); + * const [response] = await operation.promise(); */ analyzeIamPolicyLongrunning( request: protos.google.cloud.asset.v1.IAnalyzeIamPolicyLongrunningRequest, @@ -1301,18 +1345,19 @@ export class AssetServiceClient { ); } /** - * Check the status of the long running operation returned by the analyzeIamPolicyLongrunning() method. + * Check the status of the long running operation returned by `analyzeIamPolicyLongrunning()`. * @param {String} name * The operation name that will be passed. * @returns {Promise} - The promise which resolves to an object. * The decoded operation object has result and metadata field to get information from. - * - * @example: - * const decodedOperation = await checkAnalyzeIamPolicyLongrunningProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); - * + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const decodedOperation = await checkAnalyzeIamPolicyLongrunningProgress(name); + * console.log(decodedOperation.result); + * console.log(decodedOperation.done); + * console.log(decodedOperation.metadata); */ async checkAnalyzeIamPolicyLongrunningProgress( name: string @@ -1450,19 +1495,14 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is Array of [ResourceSearchResult]{@link google.cloud.asset.v1.ResourceSearchResult}. - * The client library support auto-pagination by default: it will call the API as many + * The client library will perform auto-pagination by default: it will call the API as many * times as needed and will merge results from all the pages into this array. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [ResourceSearchResult]{@link google.cloud.asset.v1.ResourceSearchResult} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [SearchAllResourcesRequest]{@link google.cloud.asset.v1.SearchAllResourcesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [SearchAllResourcesResponse]{@link google.cloud.asset.v1.SearchAllResourcesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `searchAllResourcesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllResources( request: protos.google.cloud.asset.v1.ISearchAllResourcesRequest, @@ -1510,18 +1550,7 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllResources}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link searchAllResources} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -1599,6 +1628,13 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Stream} * An object stream which emits an object representing [ResourceSearchResult]{@link google.cloud.asset.v1.ResourceSearchResult} on 'data' event. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed. Note that it can affect your quota. + * We recommend using `searchAllResourcesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllResourcesStream( request?: protos.google.cloud.asset.v1.ISearchAllResourcesRequest, @@ -1623,10 +1659,9 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllResources}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `searchAllResources`, but returns an iterable object. * + * `for`-`await`-`of` syntax is used with the iterable to get response elements on-demand. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -1703,7 +1738,18 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Object} - * An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [ResourceSearchResult]{@link google.cloud.asset.v1.ResourceSearchResult}. The API will be called under the hood as needed, once per the page, + * so you can stop the iteration when you don't need more results. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.searchAllResourcesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ searchAllResourcesAsync( request?: protos.google.cloud.asset.v1.ISearchAllResourcesRequest, @@ -1820,19 +1866,14 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is Array of [IamPolicySearchResult]{@link google.cloud.asset.v1.IamPolicySearchResult}. - * The client library support auto-pagination by default: it will call the API as many + * The client library will perform auto-pagination by default: it will call the API as many * times as needed and will merge results from all the pages into this array. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [IamPolicySearchResult]{@link google.cloud.asset.v1.IamPolicySearchResult} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [SearchAllIamPoliciesRequest]{@link google.cloud.asset.v1.SearchAllIamPoliciesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [SearchAllIamPoliciesResponse]{@link google.cloud.asset.v1.SearchAllIamPoliciesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `searchAllIamPoliciesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllIamPolicies( request: protos.google.cloud.asset.v1.ISearchAllIamPoliciesRequest, @@ -1880,18 +1921,7 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllIamPolicies}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link searchAllIamPolicies} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -1948,6 +1978,13 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Stream} * An object stream which emits an object representing [IamPolicySearchResult]{@link google.cloud.asset.v1.IamPolicySearchResult} on 'data' event. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed. Note that it can affect your quota. + * We recommend using `searchAllIamPoliciesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllIamPoliciesStream( request?: protos.google.cloud.asset.v1.ISearchAllIamPoliciesRequest, @@ -1972,10 +2009,9 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllIamPolicies}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `searchAllIamPolicies`, but returns an iterable object. * + * `for`-`await`-`of` syntax is used with the iterable to get response elements on-demand. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -2031,7 +2067,18 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Object} - * An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [IamPolicySearchResult]{@link google.cloud.asset.v1.IamPolicySearchResult}. The API will be called under the hood as needed, once per the page, + * so you can stop the iteration when you don't need more results. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.searchAllIamPoliciesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ searchAllIamPoliciesAsync( request?: protos.google.cloud.asset.v1.ISearchAllIamPoliciesRequest, @@ -2175,9 +2222,10 @@ export class AssetServiceClient { } /** - * Terminate the GRPC channel and close the client. + * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. + * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise { this.initialize(); diff --git a/packages/google-cloud-asset/src/v1beta1/asset_service_client.ts b/packages/google-cloud-asset/src/v1beta1/asset_service_client.ts index bd554294b9d..bc32ce5a590 100644 --- a/packages/google-cloud-asset/src/v1beta1/asset_service_client.ts +++ b/packages/google-cloud-asset/src/v1beta1/asset_service_client.ts @@ -57,8 +57,10 @@ export class AssetServiceClient { /** * Construct an instance of AssetServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @param {object} [options] - The configuration object. + * The options accepted by the constructor are described in detail + * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance). + * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] @@ -78,42 +80,33 @@ export class AssetServiceClient { * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. + * @param {gax.ClientConfig} [options.clientConfig] - client configuration override. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AssetServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AssetServiceClient constructor. + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AssetServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -122,6 +115,11 @@ export class AssetServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -259,6 +257,7 @@ export class AssetServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'cloudasset.googleapis.com'; @@ -267,6 +266,7 @@ export class AssetServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'cloudasset.googleapis.com'; @@ -274,6 +274,7 @@ export class AssetServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -282,6 +283,7 @@ export class AssetServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return ['https://www.googleapis.com/auth/cloud-platform']; @@ -291,8 +293,7 @@ export class AssetServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -378,7 +379,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [BatchGetAssetsHistoryResponse]{@link google.cloud.asset.v1beta1.BatchGetAssetsHistoryResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.batchGetAssetsHistory(request); */ batchGetAssetsHistory( request: protos.google.cloud.asset.v1beta1.IBatchGetAssetsHistoryRequest, @@ -499,8 +504,15 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. - * The first element of the array is an object representing [Operation]{@link google.longrunning.Operation}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const [operation] = await client.exportAssets(request); + * const [response] = await operation.promise(); */ exportAssets( request: protos.google.cloud.asset.v1beta1.IExportAssetsRequest, @@ -552,18 +564,19 @@ export class AssetServiceClient { return this.innerApiCalls.exportAssets(request, options, callback); } /** - * Check the status of the long running operation returned by the exportAssets() method. + * Check the status of the long running operation returned by `exportAssets()`. * @param {String} name * The operation name that will be passed. * @returns {Promise} - The promise which resolves to an object. * The decoded operation object has result and metadata field to get information from. - * - * @example: - * const decodedOperation = await checkExportAssetsProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); - * + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const decodedOperation = await checkExportAssetsProgress(name); + * console.log(decodedOperation.result); + * console.log(decodedOperation.done); + * console.log(decodedOperation.metadata); */ async checkExportAssetsProgress( name: string @@ -589,9 +602,10 @@ export class AssetServiceClient { } /** - * Terminate the GRPC channel and close the client. + * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. + * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise { this.initialize(); diff --git a/packages/google-cloud-asset/src/v1p1beta1/asset_service_client.ts b/packages/google-cloud-asset/src/v1p1beta1/asset_service_client.ts index f91f50ceac5..27fe5891a24 100644 --- a/packages/google-cloud-asset/src/v1p1beta1/asset_service_client.ts +++ b/packages/google-cloud-asset/src/v1p1beta1/asset_service_client.ts @@ -59,8 +59,10 @@ export class AssetServiceClient { /** * Construct an instance of AssetServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @param {object} [options] - The configuration object. + * The options accepted by the constructor are described in detail + * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance). + * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] @@ -80,42 +82,33 @@ export class AssetServiceClient { * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. + * @param {gax.ClientConfig} [options.clientConfig] - client configuration override. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AssetServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AssetServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AssetServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -124,6 +117,11 @@ export class AssetServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -249,6 +247,7 @@ export class AssetServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'cloudasset.googleapis.com'; @@ -257,6 +256,7 @@ export class AssetServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'cloudasset.googleapis.com'; @@ -264,6 +264,7 @@ export class AssetServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -272,6 +273,7 @@ export class AssetServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return ['https://www.googleapis.com/auth/cloud-platform']; @@ -281,8 +283,7 @@ export class AssetServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -370,19 +371,14 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is Array of [StandardResourceMetadata]{@link google.cloud.asset.v1p1beta1.StandardResourceMetadata}. - * The client library support auto-pagination by default: it will call the API as many + * The client library will perform auto-pagination by default: it will call the API as many * times as needed and will merge results from all the pages into this array. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [StandardResourceMetadata]{@link google.cloud.asset.v1p1beta1.StandardResourceMetadata} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [SearchAllResourcesRequest]{@link google.cloud.asset.v1p1beta1.SearchAllResourcesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [SearchAllResourcesResponse]{@link google.cloud.asset.v1p1beta1.SearchAllResourcesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `searchAllResourcesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllResources( request: protos.google.cloud.asset.v1p1beta1.ISearchAllResourcesRequest, @@ -430,18 +426,7 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllResources}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link searchAllResources} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -475,6 +460,13 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Stream} * An object stream which emits an object representing [StandardResourceMetadata]{@link google.cloud.asset.v1p1beta1.StandardResourceMetadata} on 'data' event. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed. Note that it can affect your quota. + * We recommend using `searchAllResourcesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllResourcesStream( request?: protos.google.cloud.asset.v1p1beta1.ISearchAllResourcesRequest, @@ -499,10 +491,9 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllResources}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `searchAllResources`, but returns an iterable object. * + * `for`-`await`-`of` syntax is used with the iterable to get response elements on-demand. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -535,7 +526,18 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Object} - * An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [StandardResourceMetadata]{@link google.cloud.asset.v1p1beta1.StandardResourceMetadata}. The API will be called under the hood as needed, once per the page, + * so you can stop the iteration when you don't need more results. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.searchAllResourcesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ searchAllResourcesAsync( request?: protos.google.cloud.asset.v1p1beta1.ISearchAllResourcesRequest, @@ -630,19 +632,14 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is Array of [IamPolicySearchResult]{@link google.cloud.asset.v1p1beta1.IamPolicySearchResult}. - * The client library support auto-pagination by default: it will call the API as many + * The client library will perform auto-pagination by default: it will call the API as many * times as needed and will merge results from all the pages into this array. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [IamPolicySearchResult]{@link google.cloud.asset.v1p1beta1.IamPolicySearchResult} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [SearchAllIamPoliciesRequest]{@link google.cloud.asset.v1p1beta1.SearchAllIamPoliciesRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [SearchAllIamPoliciesResponse]{@link google.cloud.asset.v1p1beta1.SearchAllIamPoliciesResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `searchAllIamPoliciesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllIamPolicies( request: protos.google.cloud.asset.v1p1beta1.ISearchAllIamPoliciesRequest, @@ -690,18 +687,7 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllIamPolicies}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link searchAllIamPolicies} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -730,6 +716,13 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Stream} * An object stream which emits an object representing [IamPolicySearchResult]{@link google.cloud.asset.v1p1beta1.IamPolicySearchResult} on 'data' event. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed. Note that it can affect your quota. + * We recommend using `searchAllIamPoliciesAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ searchAllIamPoliciesStream( request?: protos.google.cloud.asset.v1p1beta1.ISearchAllIamPoliciesRequest, @@ -754,10 +747,9 @@ export class AssetServiceClient { } /** - * Equivalent to {@link searchAllIamPolicies}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `searchAllIamPolicies`, but returns an iterable object. * + * `for`-`await`-`of` syntax is used with the iterable to get response elements on-demand. * @param {Object} request * The request object that will be sent. * @param {string} request.scope @@ -785,7 +777,18 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Object} - * An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [IamPolicySearchResult]{@link google.cloud.asset.v1p1beta1.IamPolicySearchResult}. The API will be called under the hood as needed, once per the page, + * so you can stop the iteration when you don't need more results. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.searchAllIamPoliciesAsync(request); + * for await (const response of iterable) { + * // process response + * } */ searchAllIamPoliciesAsync( request?: protos.google.cloud.asset.v1p1beta1.ISearchAllIamPoliciesRequest, @@ -813,9 +816,10 @@ export class AssetServiceClient { } /** - * Terminate the GRPC channel and close the client. + * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. + * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise { this.initialize(); diff --git a/packages/google-cloud-asset/src/v1p2beta1/asset_service_client.ts b/packages/google-cloud-asset/src/v1p2beta1/asset_service_client.ts index 955d9fede69..f06289a9209 100644 --- a/packages/google-cloud-asset/src/v1p2beta1/asset_service_client.ts +++ b/packages/google-cloud-asset/src/v1p2beta1/asset_service_client.ts @@ -51,8 +51,10 @@ export class AssetServiceClient { /** * Construct an instance of AssetServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @param {object} [options] - The configuration object. + * The options accepted by the constructor are described in detail + * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance). + * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] @@ -72,42 +74,33 @@ export class AssetServiceClient { * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. + * @param {gax.ClientConfig} [options.clientConfig] - client configuration override. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AssetServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AssetServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AssetServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -116,6 +109,11 @@ export class AssetServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -243,6 +241,7 @@ export class AssetServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'cloudasset.googleapis.com'; @@ -251,6 +250,7 @@ export class AssetServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'cloudasset.googleapis.com'; @@ -258,6 +258,7 @@ export class AssetServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -266,6 +267,7 @@ export class AssetServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return ['https://www.googleapis.com/auth/cloud-platform']; @@ -275,8 +277,7 @@ export class AssetServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -343,7 +344,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Feed]{@link google.cloud.asset.v1p2beta1.Feed}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.createFeed(request); */ createFeed( request: protos.google.cloud.asset.v1p2beta1.ICreateFeedRequest, @@ -428,7 +433,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Feed]{@link google.cloud.asset.v1p2beta1.Feed}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.getFeed(request); */ getFeed( request: protos.google.cloud.asset.v1p2beta1.IGetFeedRequest, @@ -512,7 +521,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [ListFeedsResponse]{@link google.cloud.asset.v1p2beta1.ListFeedsResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.listFeeds(request); */ listFeeds( request: protos.google.cloud.asset.v1p2beta1.IListFeedsRequest, @@ -602,7 +615,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Feed]{@link google.cloud.asset.v1p2beta1.Feed}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.updateFeed(request); */ updateFeed( request: protos.google.cloud.asset.v1p2beta1.IUpdateFeedRequest, @@ -687,7 +704,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [Empty]{@link google.protobuf.Empty}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.deleteFeed(request); */ deleteFeed( request: protos.google.cloud.asset.v1p2beta1.IDeleteFeedRequest, @@ -852,9 +873,10 @@ export class AssetServiceClient { } /** - * Terminate the GRPC channel and close the client. + * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. + * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise { this.initialize(); diff --git a/packages/google-cloud-asset/src/v1p4beta1/asset_service_client.ts b/packages/google-cloud-asset/src/v1p4beta1/asset_service_client.ts index 0246454c843..6380744f67b 100644 --- a/packages/google-cloud-asset/src/v1p4beta1/asset_service_client.ts +++ b/packages/google-cloud-asset/src/v1p4beta1/asset_service_client.ts @@ -57,8 +57,10 @@ export class AssetServiceClient { /** * Construct an instance of AssetServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @param {object} [options] - The configuration object. + * The options accepted by the constructor are described in detail + * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance). + * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] @@ -78,42 +80,33 @@ export class AssetServiceClient { * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. + * @param {gax.ClientConfig} [options.clientConfig] - client configuration override. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AssetServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AssetServiceClient constructor. + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AssetServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -122,6 +115,11 @@ export class AssetServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -266,6 +264,7 @@ export class AssetServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'cloudasset.googleapis.com'; @@ -274,6 +273,7 @@ export class AssetServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'cloudasset.googleapis.com'; @@ -281,6 +281,7 @@ export class AssetServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -289,6 +290,7 @@ export class AssetServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return ['https://www.googleapis.com/auth/cloud-platform']; @@ -298,8 +300,7 @@ export class AssetServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -359,7 +360,11 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is an object representing [AnalyzeIamPolicyResponse]{@link google.cloud.asset.v1p4beta1.AnalyzeIamPolicyResponse}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods) + * for more details and examples. + * @example + * const [response] = await client.analyzeIamPolicy(request); */ analyzeIamPolicy( request: protos.google.cloud.asset.v1p4beta1.IAnalyzeIamPolicyRequest, @@ -459,8 +464,15 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. - * The first element of the array is an object representing [Operation]{@link google.longrunning.Operation}. - * The promise has a method named "cancel" which cancels the ongoing API call. + * The first element of the array is an object representing + * a long running operation. Its `promise()` method returns a promise + * you can `await` for. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const [operation] = await client.exportIamPolicyAnalysis(request); + * const [response] = await operation.promise(); */ exportIamPolicyAnalysis( request: protos.google.cloud.asset.v1p4beta1.IExportIamPolicyAnalysisRequest, @@ -516,18 +528,19 @@ export class AssetServiceClient { ); } /** - * Check the status of the long running operation returned by the exportIamPolicyAnalysis() method. + * Check the status of the long running operation returned by `exportIamPolicyAnalysis()`. * @param {String} name * The operation name that will be passed. * @returns {Promise} - The promise which resolves to an object. * The decoded operation object has result and metadata field to get information from. - * - * @example: - * const decodedOperation = await checkExportIamPolicyAnalysisProgress(name); - * console.log(decodedOperation.result); - * console.log(decodedOperation.done); - * console.log(decodedOperation.metadata); - * + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#long-running-operations) + * for more details and examples. + * @example + * const decodedOperation = await checkExportIamPolicyAnalysisProgress(name); + * console.log(decodedOperation.result); + * console.log(decodedOperation.done); + * console.log(decodedOperation.metadata); */ async checkExportIamPolicyAnalysisProgress( name: string @@ -553,9 +566,10 @@ export class AssetServiceClient { } /** - * Terminate the GRPC channel and close the client. + * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. + * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise { this.initialize(); diff --git a/packages/google-cloud-asset/src/v1p5beta1/asset_service_client.ts b/packages/google-cloud-asset/src/v1p5beta1/asset_service_client.ts index 12b511edabc..3072e67d686 100644 --- a/packages/google-cloud-asset/src/v1p5beta1/asset_service_client.ts +++ b/packages/google-cloud-asset/src/v1p5beta1/asset_service_client.ts @@ -59,8 +59,10 @@ export class AssetServiceClient { /** * Construct an instance of AssetServiceClient. * - * @param {object} [options] - The configuration object. See the subsequent - * parameters for more details. + * @param {object} [options] - The configuration object. + * The options accepted by the constructor are described in detail + * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance). + * The common options are: * @param {object} [options.credentials] - Credentials object. * @param {string} [options.credentials.client_email] * @param {string} [options.credentials.private_key] @@ -80,42 +82,33 @@ export class AssetServiceClient { * your project ID will be detected automatically. * @param {string} [options.apiEndpoint] - The domain name of the * API remote host. + * @param {gax.ClientConfig} [options.clientConfig] - client configuration override. + * TODO(@alexander-fenster): link to gax documentation. + * @param {boolean} fallback - Use HTTP fallback mode. + * In fallback mode, a special browser-compatible transport implementation is used + * instead of gRPC transport. In browser context (if the `window` object is defined) + * the fallback mode is enabled automatically; set `options.fallback` to `false` + * if you need to override this behavior. */ - constructor(opts?: ClientOptions) { - // Ensure that options include the service address and port. + // Ensure that options include all the required fields. const staticMembers = this.constructor as typeof AssetServiceClient; const servicePath = - opts && opts.servicePath - ? opts.servicePath - : opts && opts.apiEndpoint - ? opts.apiEndpoint - : staticMembers.servicePath; - const port = opts && opts.port ? opts.port : staticMembers.port; - - if (!opts) { - opts = {servicePath, port}; + opts?.servicePath || opts?.apiEndpoint || staticMembers.servicePath; + const port = opts?.port || staticMembers.port; + const clientConfig = opts?.clientConfig ?? {}; + const fallback = opts?.fallback ?? typeof window !== 'undefined'; + opts = Object.assign({servicePath, port, clientConfig, fallback}, opts); + + // If scopes are unset in options and we're connecting to a non-default endpoint, set scopes just in case. + if (servicePath !== staticMembers.servicePath && !('scopes' in opts)) { + opts['scopes'] = staticMembers.scopes; } - opts.servicePath = opts.servicePath || servicePath; - opts.port = opts.port || port; - - // users can override the config from client side, like retry codes name. - // The detailed structure of the clientConfig can be found here: https://github.com/googleapis/gax-nodejs/blob/master/src/gax.ts#L546 - // The way to override client config for Showcase API: - // - // const customConfig = {"interfaces": {"google.showcase.v1beta1.Echo": {"methods": {"Echo": {"retry_codes_name": "idempotent", "retry_params_name": "default"}}}}} - // const showcaseClient = new showcaseClient({ projectId, customConfig }); - opts.clientConfig = opts.clientConfig || {}; - - // If we're running in browser, it's OK to omit `fallback` since - // google-gax has `browser` field in its `package.json`. - // For Electron (which does not respect `browser` field), - // pass `{fallback: true}` to the AssetServiceClient constructor. + + // Choose either gRPC or proto-over-HTTP implementation of google-gax. this._gaxModule = opts.fallback ? gax.fallback : gax; - // Create a `gaxGrpc` object, with any grpc-specific options - // sent to the client. - opts.scopes = (this.constructor as typeof AssetServiceClient).scopes; + // Create a `gaxGrpc` object, with any grpc-specific options sent to the client. this._gaxGrpc = new this._gaxModule.GrpcClient(opts); // Save options to use in initialize() method. @@ -124,6 +117,11 @@ export class AssetServiceClient { // Save the auth object to the client, for use by other methods. this.auth = this._gaxGrpc.auth as gax.GoogleAuth; + // Set the default scopes in auth client if needed. + if (servicePath === staticMembers.servicePath) { + this.auth.defaultScopes = staticMembers.scopes; + } + // Determine the client header string. const clientHeader = [`gax/${this._gaxModule.version}`, `gapic/${version}`]; if (typeof process !== 'undefined' && 'versions' in process) { @@ -241,6 +239,7 @@ export class AssetServiceClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'cloudasset.googleapis.com'; @@ -249,6 +248,7 @@ export class AssetServiceClient { /** * The DNS address for this API service - same as servicePath(), * exists for compatibility reasons. + * @returns {string} The DNS address for this service. */ static get apiEndpoint() { return 'cloudasset.googleapis.com'; @@ -256,6 +256,7 @@ export class AssetServiceClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -264,6 +265,7 @@ export class AssetServiceClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return ['https://www.googleapis.com/auth/cloud-platform']; @@ -273,8 +275,7 @@ export class AssetServiceClient { getProjectId(callback: Callback): void; /** * Return the project ID used by this class. - * @param {function(Error, string)} callback - the callback to - * be called with the current project Id. + * @returns {Promise} A promise that resolves to string containing the project ID. */ getProjectId( callback?: Callback @@ -358,19 +359,14 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Promise} - The promise which resolves to an array. * The first element of the array is Array of [Asset]{@link google.cloud.asset.v1p5beta1.Asset}. - * The client library support auto-pagination by default: it will call the API as many + * The client library will perform auto-pagination by default: it will call the API as many * times as needed and will merge results from all the pages into this array. - * - * When autoPaginate: false is specified through options, the array has three elements. - * The first element is Array of [Asset]{@link google.cloud.asset.v1p5beta1.Asset} that corresponds to - * the one page received from the API server. - * If the second element is not null it contains the request object of type [ListAssetsRequest]{@link google.cloud.asset.v1p5beta1.ListAssetsRequest} - * that can be used to obtain the next page of the results. - * If it is null, the next page does not exist. - * The third element contains the raw response received from the API server. Its type is - * [ListAssetsResponse]{@link google.cloud.asset.v1p5beta1.ListAssetsResponse}. - * - * The promise has a method named "cancel" which cancels the ongoing API call. + * Note that it can affect your quota. + * We recommend using `listAssetsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listAssets( request: protos.google.cloud.asset.v1p5beta1.IListAssetsRequest, @@ -418,18 +414,7 @@ export class AssetServiceClient { } /** - * Equivalent to {@link listAssets}, but returns a NodeJS Stream object. - * - * This fetches the paged responses for {@link listAssets} continuously - * and invokes the callback registered for 'data' event for each element in the - * responses. - * - * The returned object has 'end' method when no more elements are required. - * - * autoPaginate option will be ignored. - * - * @see {@link https://nodejs.org/api/stream.html} - * + * Equivalent to `method.name.toCamelCase()`, but returns a NodeJS Stream object. * @param {Object} request * The request object that will be sent. * @param {string} request.parent @@ -463,6 +448,13 @@ export class AssetServiceClient { * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Stream} * An object stream which emits an object representing [Asset]{@link google.cloud.asset.v1p5beta1.Asset} on 'data' event. + * The client library will perform auto-pagination by default: it will call the API as many + * times as needed. Note that it can affect your quota. + * We recommend using `listAssetsAsync()` + * method described below for async iteration which you can stop as needed. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. */ listAssetsStream( request?: protos.google.cloud.asset.v1p5beta1.IListAssetsRequest, @@ -487,10 +479,9 @@ export class AssetServiceClient { } /** - * Equivalent to {@link listAssets}, but returns an iterable object. - * - * for-await-of syntax is used with the iterable to recursively get response element on-demand. + * Equivalent to `listAssets`, but returns an iterable object. * + * `for`-`await`-`of` syntax is used with the iterable to get response elements on-demand. * @param {Object} request * The request object that will be sent. * @param {string} request.parent @@ -523,7 +514,18 @@ export class AssetServiceClient { * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. * @returns {Object} - * An iterable Object that conforms to @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols. + * An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). + * When you iterate the returned iterable, each element will be an object representing + * [Asset]{@link google.cloud.asset.v1p5beta1.Asset}. The API will be called under the hood as needed, once per the page, + * so you can stop the iteration when you don't need more results. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination) + * for more details and examples. + * @example + * const iterable = client.listAssetsAsync(request); + * for await (const response of iterable) { + * // process response + * } */ listAssetsAsync( request?: protos.google.cloud.asset.v1p5beta1.IListAssetsRequest, @@ -549,9 +551,10 @@ export class AssetServiceClient { } /** - * Terminate the GRPC channel and close the client. + * Terminate the gRPC channel and close the client. * * The client will no longer be usable and all future behavior is undefined. + * @returns {Promise} A promise that resolves when the client is closed. */ close(): Promise { this.initialize(); diff --git a/packages/google-cloud-asset/synth.metadata b/packages/google-cloud-asset/synth.metadata index cfca8a811b5..ff6c0fcf8fe 100644 --- a/packages/google-cloud-asset/synth.metadata +++ b/packages/google-cloud-asset/synth.metadata @@ -19,7 +19,7 @@ "git": { "name": "synthtool", "remote": "https://github.com/googleapis/synthtool.git", - "sha": "ba9918cd22874245b55734f57470c719b577e591" + "sha": "1f1148d3c7a7a52f0c98077f976bd9b3c948ee2b" } } ], @@ -132,6 +132,7 @@ "README.md", "api-extractor.json", "linkinator.config.json", + "package-lock.json.160311084", "protos/google/cloud/asset/v1/asset_service.proto", "protos/google/cloud/asset/v1/assets.proto", "protos/google/cloud/asset/v1beta1/asset_service.proto", @@ -149,6 +150,7 @@ "protos/protos.json", "renovate.json", "samples/README.md", + "samples/package-lock.json.2464353656", "src/index.ts", "src/v1/asset_service_client.ts", "src/v1/asset_service_client_config.json", diff --git a/packages/google-cloud-asset/system-test/fixtures/sample/src/index.ts b/packages/google-cloud-asset/system-test/fixtures/sample/src/index.ts index f1056a37fb9..b551d6664dc 100644 --- a/packages/google-cloud-asset/system-test/fixtures/sample/src/index.ts +++ b/packages/google-cloud-asset/system-test/fixtures/sample/src/index.ts @@ -18,8 +18,15 @@ import {AssetServiceClient} from '@google-cloud/asset'; +// check that the client class type name can be used +function doStuffWithAssetServiceClient(client: AssetServiceClient) { + client.close(); +} + function main() { - new AssetServiceClient(); + // check that the client instance can be created + const assetServiceClient = new AssetServiceClient(); + doStuffWithAssetServiceClient(assetServiceClient); } main(); diff --git a/packages/google-cloud-asset/system-test/install.ts b/packages/google-cloud-asset/system-test/install.ts index 4c1ba3eb79a..39d90f771de 100644 --- a/packages/google-cloud-asset/system-test/install.ts +++ b/packages/google-cloud-asset/system-test/install.ts @@ -20,32 +20,32 @@ import {packNTest} from 'pack-n-play'; import {readFileSync} from 'fs'; import {describe, it} from 'mocha'; -describe('typescript consumer tests', () => { - it('should have correct type signature for typescript users', async function () { +describe('📦 pack-n-play test', () => { + it('TypeScript code', async function () { this.timeout(300000); const options = { - packageDir: process.cwd(), // path to your module. + packageDir: process.cwd(), sample: { - description: 'typescript based user can use the type definitions', + description: 'TypeScript user can use the type definitions', ts: readFileSync( './system-test/fixtures/sample/src/index.ts' ).toString(), }, }; - await packNTest(options); // will throw upon error. + await packNTest(options); }); - it('should have correct type signature for javascript users', async function () { + it('JavaScript code', async function () { this.timeout(300000); const options = { - packageDir: process.cwd(), // path to your module. + packageDir: process.cwd(), sample: { - description: 'typescript based user can use the type definitions', + description: 'JavaScript user can use the library', ts: readFileSync( './system-test/fixtures/sample/src/index.js' ).toString(), }, }; - await packNTest(options); // will throw upon error. + await packNTest(options); }); });