diff --git a/templates/typescript_gapic/_util.njk b/templates/typescript_gapic/_util.njk index c54d2dd6e..ea0e548a9 100644 --- a/templates/typescript_gapic/_util.njk +++ b/templates/typescript_gapic/_util.njk @@ -15,22 +15,6 @@ See the License for the specific language governing permissions and limitations under the License. -#} -{%- macro initRequestWithHeaderParam(method) -%} - const request: protosTypes{{ toInterface(method.inputInterface) }} = {}; -{%- if method.headerRequestParams.length > 1 %} -{%- set chain = "request" -%} -{%- for field in method.headerRequestParams.slice(0, -1) %} - {{ chain }}.{{ field.toCamelCase() }} = {}; -{%- set chain = chain + "." + field.toCamelCase() -%} -{%- endfor %} - {{ chain }}.{{ method.headerRequestParams.slice(-1)[0] }} = ''; -{%- endif %} -{%- endmacro -%} - -{%- macro toInterface(type) -%} -{%- set index = type.lastIndexOf('.') -%} -{{ type.substring(0, index + 1) + 'I' + type.substring(index + 1) }} -{%- endmacro -%} {%- macro printComments(method, service) -%} {{- printCommentsForMethod(method) }} @@ -40,22 +24,19 @@ limitations under the License. {{- printReturn(method, service) }} {%- endmacro %} -{%- macro printCommentsForParams(method) -%} -{% if not method.clientStreaming %} -{%- set commentsMap = method.paramComment -%} -{%- for oneComment in commentsMap -%} -{%- set type = oneComment.paramType -%} -{%- if type.startsWith('.') %} - * @param { {{- type.substring(1) -}} } request.{{ oneComment.paramName }} -{%- else %} - * @param { {{- convertParamType(oneComment.paramType) -}} } request.{{ oneComment.paramName }} -{%- endif -%} -{%- set lines = oneComment.comments -%} -{%- for line in lines %} - * {{ line.replaceAll('*/', '* /') | safe}} -{%- endfor -%} -{%- endfor -%} -{%- endif %} +{%- macro printCommentsPageStream(method) -%} + {{- printPageStreamHeader(method) -}} + {{- printRequest(method) -}} + {{- printCommentsForParams(method) -}} + {{- printOptions() -}} + {{- printReturnPageStream(method) }} +{%- endmacro -%} + +{%- macro printCommentsForService(service) -%} +{%- set lines = service.comments -%} +{% for line in lines %} + * {{ line | safe}} +{%- endfor %} {%- endmacro -%} {%- macro printCommentsForMethod(method) -%} @@ -65,11 +46,19 @@ limitations under the License. {%- endfor %} {%- endmacro -%} -{%- macro printCommentsForService(service) -%} -{%- set lines = service.comments -%} -{% for line in lines %} - * {{ line | safe}} -{%- endfor %} +{%- macro printPageStreamHeader(method) %} + * Equivalent to {@link {{ method.name.toCamelCase() }}}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link {{ method.name.toCamelCase() }}} 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} + * {%- endmacro -%} {%- macro printRequest(method) %} @@ -79,6 +68,24 @@ limitations under the License. {%- endif %} {%- endmacro -%} +{%- macro printCommentsForParams(method) -%} +{% if not method.clientStreaming %} +{%- set commentsMap = method.paramComment -%} +{%- for oneComment in commentsMap -%} +{%- set type = oneComment.paramType -%} +{%- if type.startsWith('.') %} + * @param { {{- type.substring(1) -}} } request.{{ oneComment.paramName }} +{%- else %} + * @param { {{- convertParamType(oneComment.paramType) -}} } request.{{ oneComment.paramName }} +{%- endif -%} +{%- set lines = oneComment.comments -%} +{%- for line in lines %} + * {{ line.replaceAll('*/', '* /') | safe}} +{%- endfor -%} +{%- endfor -%} +{%- endif %} +{%- endmacro -%} + {%- macro printOptions(type) %} * @param {object} [options] * Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details. @@ -132,11 +139,33 @@ limitations under the License. * will emit objects representing [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}} on 'data' event asynchronously. {%- endmacro -%} +{%- macro printReturnPageStream(method) %} + * @returns {Stream} + * An object stream which emits an object representing [{{- toMessageName(method.pagingResponseType) -}}]{@link {{ method.pagingResponseType.substring(1) }}} on 'data' event. +{%- endmacro -%} + {%- macro toMessageName(messageType) -%} {%- set arr = messageType.split('.') %} {{- arr[arr.length - 1] -}} {%- endmacro -%} +{%- macro initRequestWithHeaderParam(method) -%} + const request: protosTypes{{ toInterface(method.inputInterface) }} = {}; +{%- if method.headerRequestParams.length > 1 %} +{%- set chain = "request" -%} +{%- for field in method.headerRequestParams.slice(0, -1) %} + {{ chain }}.{{ field.toCamelCase() }} = {}; +{%- set chain = chain + "." + field.toCamelCase() -%} +{%- endfor %} + {{ chain }}.{{ method.headerRequestParams.slice(-1)[0] }} = ''; +{%- endif %} +{%- endmacro -%} + +{%- macro toInterface(type) -%} +{%- set index = type.lastIndexOf('.') -%} +{{ type.substring(0, index + 1) + 'I' + type.substring(index + 1) }} +{%- endmacro -%} + {%- macro convertParamType(paramType) -%} {%- if paramType.includes('TYPE_BYTES') %} {%- set type = paramType.replace('TYPE_BYTES', 'Buffer') %} diff --git a/templates/typescript_gapic/src/$version/$service_client.ts.njk b/templates/typescript_gapic/src/$version/$service_client.ts.njk index e12b0dc6a..60ca43dc4 100644 --- a/templates/typescript_gapic/src/$version/$service_client.ts.njk +++ b/templates/typescript_gapic/src/$version/$service_client.ts.njk @@ -569,6 +569,9 @@ export class {{ service.name }}Client { return this._innerApiCalls.{{ method.name.toCamelCase() }}(request, options, callback); } +/** +{{- util.printCommentsPageStream(method) }} + */ {{ method.name.toCamelCase() }}Stream( request?: protosTypes{{ util.toInterface(method.inputInterface) }}, options?: gax.CallOptions | {}): diff --git a/typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline b/typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline index 2c5e28d12..145e6e2e8 100644 --- a/typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline +++ b/typescript/test/testdata/keymanager/src/v1/key_management_service_client.ts.baseline @@ -1634,6 +1634,42 @@ export class KeyManagementServiceClient { return this._innerApiCalls.listKeyRings(request, options, callback); } +/** + * Equivalent to {@link listKeyRings}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listKeyRings} 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} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The resource name of the location associated with the + * [KeyRings][google.cloud.kms.v1.KeyRing], in the format `projects/* /locations/*`. + * @param {number} request.page_size + * Optional limit on the number of [KeyRings][google.cloud.kms.v1.KeyRing] to include in the + * response. Further [KeyRings][google.cloud.kms.v1.KeyRing] can subsequently be obtained by + * including the [ListKeyRingsResponse.next_page_token][google.cloud.kms.v1.ListKeyRingsResponse.next_page_token] in a subsequent + * request. If unspecified, the server will pick an appropriate default. + * @param {string} request.page_token + * Optional pagination token, returned earlier via + * [ListKeyRingsResponse.next_page_token][google.cloud.kms.v1.ListKeyRingsResponse.next_page_token]. + * @param {string} request.filter + * Optional. Only include resources that match the filter in the response. + * @param {string} request.order_by + * Optional. Specify how the results should be sorted. If not specified, the + * results will be sorted in the default order. + * @param {object} [options] + * 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 [KeyRing]{@link google.cloud.kms.v1.KeyRing} on 'data' event. + */ listKeyRingsStream( request?: protosTypes.google.cloud.kms.v1.IListKeyRingsRequest, options?: gax.CallOptions | {}): @@ -1732,6 +1768,44 @@ export class KeyManagementServiceClient { return this._innerApiCalls.listCryptoKeys(request, options, callback); } +/** + * Equivalent to {@link listCryptoKeys}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listCryptoKeys} 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} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The resource name of the [KeyRing][google.cloud.kms.v1.KeyRing] to list, in the format + * `projects/* /locations/* /keyRings/*`. + * @param {number} request.page_size + * Optional limit on the number of [CryptoKeys][google.cloud.kms.v1.CryptoKey] to include in the + * response. Further [CryptoKeys][google.cloud.kms.v1.CryptoKey] can subsequently be obtained by + * including the [ListCryptoKeysResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeysResponse.next_page_token] in a subsequent + * request. If unspecified, the server will pick an appropriate default. + * @param {string} request.page_token + * Optional pagination token, returned earlier via + * [ListCryptoKeysResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeysResponse.next_page_token]. + * @param {google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionView} request.version_view + * The fields of the primary version to include in the response. + * @param {string} request.filter + * Optional. Only include resources that match the filter in the response. + * @param {string} request.order_by + * Optional. Specify how the results should be sorted. If not specified, the + * results will be sorted in the default order. + * @param {object} [options] + * 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 [CryptoKey]{@link google.cloud.kms.v1.CryptoKey} on 'data' event. + */ listCryptoKeysStream( request?: protosTypes.google.cloud.kms.v1.IListCryptoKeysRequest, options?: gax.CallOptions | {}): @@ -1831,6 +1905,45 @@ export class KeyManagementServiceClient { return this._innerApiCalls.listCryptoKeyVersions(request, options, callback); } +/** + * Equivalent to {@link listCryptoKeyVersions}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listCryptoKeyVersions} 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} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The resource name of the [CryptoKey][google.cloud.kms.v1.CryptoKey] to list, in the format + * `projects/* /locations/* /keyRings/* /cryptoKeys/*`. + * @param {number} request.page_size + * Optional limit on the number of [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] to + * include in the response. Further [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] can + * subsequently be obtained by including the + * [ListCryptoKeyVersionsResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeyVersionsResponse.next_page_token] in a subsequent request. + * If unspecified, the server will pick an appropriate default. + * @param {string} request.page_token + * Optional pagination token, returned earlier via + * [ListCryptoKeyVersionsResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeyVersionsResponse.next_page_token]. + * @param {google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionView} request.view + * The fields to include in the response. + * @param {string} request.filter + * Optional. Only include resources that match the filter in the response. + * @param {string} request.order_by + * Optional. Specify how the results should be sorted. If not specified, the + * results will be sorted in the default order. + * @param {object} [options] + * 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 [CryptoKeyVersion]{@link google.cloud.kms.v1.CryptoKeyVersion} on 'data' event. + */ listCryptoKeyVersionsStream( request?: protosTypes.google.cloud.kms.v1.IListCryptoKeyVersionsRequest, options?: gax.CallOptions | {}): @@ -1927,6 +2040,42 @@ export class KeyManagementServiceClient { return this._innerApiCalls.listImportJobs(request, options, callback); } +/** + * Equivalent to {@link listImportJobs}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listImportJobs} 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} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The resource name of the [KeyRing][google.cloud.kms.v1.KeyRing] to list, in the format + * `projects/* /locations/* /keyRings/*`. + * @param {number} request.page_size + * Optional limit on the number of [ImportJobs][google.cloud.kms.v1.ImportJob] to include in the + * response. Further [ImportJobs][google.cloud.kms.v1.ImportJob] can subsequently be obtained by + * including the [ListImportJobsResponse.next_page_token][google.cloud.kms.v1.ListImportJobsResponse.next_page_token] in a subsequent + * request. If unspecified, the server will pick an appropriate default. + * @param {string} request.page_token + * Optional pagination token, returned earlier via + * [ListImportJobsResponse.next_page_token][google.cloud.kms.v1.ListImportJobsResponse.next_page_token]. + * @param {string} request.filter + * Optional. Only include resources that match the filter in the response. + * @param {string} request.order_by + * Optional. Specify how the results should be sorted. If not specified, the + * results will be sorted in the default order. + * @param {object} [options] + * 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 [ImportJob]{@link google.cloud.kms.v1.ImportJob} on 'data' event. + */ listImportJobsStream( request?: protosTypes.google.cloud.kms.v1.IListImportJobsRequest, options?: gax.CallOptions | {}): diff --git a/typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline b/typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline index eb238410f..172cf27b5 100644 --- a/typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline +++ b/typescript/test/testdata/showcase/src/v1beta1/echo_client.ts.baseline @@ -565,6 +565,32 @@ export class EchoClient { return this._innerApiCalls.pagedExpand(request, options, callback); } +/** + * Equivalent to {@link pagedExpand}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link pagedExpand} 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} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.content + * The string to expand. + * @param {number} request.page_size + * The amount of words to returned in each page. + * @param {string} request.page_token + * The position of the page to be returned. + * @param {object} [options] + * 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 [EchoResponse]{@link google.showcase.v1beta1.EchoResponse} on 'data' event. + */ pagedExpandStream( request?: protosTypes.google.showcase.v1beta1.IPagedExpandRequest, options?: gax.CallOptions | {}): diff --git a/typescript/test/testdata/translate/src/v3beta1/translation_service_client.ts.baseline b/typescript/test/testdata/translate/src/v3beta1/translation_service_client.ts.baseline index a3a763bca..10bbdc3f8 100644 --- a/typescript/test/testdata/translate/src/v3beta1/translation_service_client.ts.baseline +++ b/typescript/test/testdata/translate/src/v3beta1/translation_service_client.ts.baseline @@ -1001,6 +1001,40 @@ export class TranslationServiceClient { return this._innerApiCalls.listGlossaries(request, options, callback); } +/** + * Equivalent to {@link listGlossaries}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listGlossaries} 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} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * Required. The name of the project from which to list all of the glossaries. + * @param {number} request.page_size + * Optional. Requested page size. The server may return fewer glossaries than + * requested. If unspecified, the server picks an appropriate default. + * @param {string} request.page_token + * Optional. A token identifying a page of results the server should return. + * Typically, this is the value of [ListGlossariesResponse.next_page_token] + * returned from the previous call to `ListGlossaries` method. + * The first page is returned if `page_token`is empty or missing. + * @param {string} request.filter + * Optional. Filter specifying constraints of a list operation. + * Filtering is not supported yet, and the parameter currently has no effect. + * If missing, no filtering is performed. + * @param {object} [options] + * 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 [Glossary]{@link google.cloud.translation.v3beta1.Glossary} on 'data' event. + */ listGlossariesStream( request?: protosTypes.google.cloud.translation.v3beta1.IListGlossariesRequest, options?: gax.CallOptions | {}):