diff --git a/packages/google-cloud-bigquery-storage/package.json b/packages/google-cloud-bigquery-storage/package.json index d7f80ef108d..6f9873f5c5f 100644 --- a/packages/google-cloud-bigquery-storage/package.json +++ b/packages/google-cloud-bigquery-storage/package.json @@ -29,7 +29,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-bigquery-storage/src/index.ts b/packages/google-cloud-bigquery-storage/src/index.ts index 8716f5a6ad2..3c75be7738d 100644 --- a/packages/google-cloud-bigquery-storage/src/index.ts +++ b/packages/google-cloud-bigquery-storage/src/index.ts @@ -19,7 +19,9 @@ import * as v1 from './v1'; import * as v1beta1 from './v1beta1'; const BigQueryReadClient = v1.BigQueryReadClient; +type BigQueryReadClient = v1.BigQueryReadClient; const BigQueryStorageClient = v1beta1.BigQueryStorageClient; +type BigQueryStorageClient = v1beta1.BigQueryStorageClient; export {v1, BigQueryReadClient, v1beta1, BigQueryStorageClient}; // For compatibility with JavaScript libraries we need to provide this default export: // tslint:disable-next-line no-default-export diff --git a/packages/google-cloud-bigquery-storage/src/v1/big_query_read_client.ts b/packages/google-cloud-bigquery-storage/src/v1/big_query_read_client.ts index dba8fffa0d0..d3cdbc68257 100644 --- a/packages/google-cloud-bigquery-storage/src/v1/big_query_read_client.ts +++ b/packages/google-cloud-bigquery-storage/src/v1/big_query_read_client.ts @@ -53,8 +53,10 @@ export class BigQueryReadClient { /** * Construct an instance of BigQueryReadClient. * - * @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] @@ -74,42 +76,33 @@ export class BigQueryReadClient { * 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 BigQueryReadClient; 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 BigQueryReadClient 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 BigQueryReadClient).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. @@ -118,6 +111,11 @@ export class BigQueryReadClient { // 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) { @@ -251,6 +249,7 @@ export class BigQueryReadClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'bigquerystorage.googleapis.com'; @@ -259,6 +258,7 @@ export class BigQueryReadClient { /** * 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 'bigquerystorage.googleapis.com'; @@ -266,6 +266,7 @@ export class BigQueryReadClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -274,6 +275,7 @@ export class BigQueryReadClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -287,8 +289,7 @@ export class BigQueryReadClient { 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 BigQueryReadClient { * 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 [ReadSession]{@link google.cloud.bigquery.storage.v1.ReadSession}. - * 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.createReadSession(request); */ createReadSession( request: protos.google.cloud.bigquery.storage.v1.ICreateReadSessionRequest, @@ -491,7 +496,11 @@ export class BigQueryReadClient { * 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 [SplitReadStreamResponse]{@link google.cloud.bigquery.storage.v1.SplitReadStreamResponse}. - * 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.splitReadStream(request); */ splitReadStream( request: protos.google.cloud.bigquery.storage.v1.ISplitReadStreamRequest, @@ -562,6 +571,13 @@ export class BigQueryReadClient { * 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 [ReadRowsResponse]{@link google.cloud.bigquery.storage.v1.ReadRowsResponse} on 'data' event. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming) + * for more details and examples. + * @example + * const stream = client.readRows(request); + * stream.on('data', (response) => { ... }); + * stream.on('end', () => { ... }); */ readRows( request?: protos.google.cloud.bigquery.storage.v1.IReadRowsRequest, @@ -731,9 +747,10 @@ export class BigQueryReadClient { } /** - * 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-bigquery-storage/src/v1beta1/big_query_storage_client.ts b/packages/google-cloud-bigquery-storage/src/v1beta1/big_query_storage_client.ts index 8964e40f5c5..937f3012e43 100644 --- a/packages/google-cloud-bigquery-storage/src/v1beta1/big_query_storage_client.ts +++ b/packages/google-cloud-bigquery-storage/src/v1beta1/big_query_storage_client.ts @@ -53,8 +53,10 @@ export class BigQueryStorageClient { /** * Construct an instance of BigQueryStorageClient. * - * @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] @@ -74,42 +76,33 @@ export class BigQueryStorageClient { * 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 BigQueryStorageClient; 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 BigQueryStorageClient 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 BigQueryStorageClient).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. @@ -118,6 +111,11 @@ export class BigQueryStorageClient { // 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) { @@ -254,6 +252,7 @@ export class BigQueryStorageClient { /** * The DNS address for this API service. + * @returns {string} The DNS address for this service. */ static get servicePath() { return 'bigquerystorage.googleapis.com'; @@ -262,6 +261,7 @@ export class BigQueryStorageClient { /** * 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 'bigquerystorage.googleapis.com'; @@ -269,6 +269,7 @@ export class BigQueryStorageClient { /** * The port for this API service. + * @returns {number} The default port for this service. */ static get port() { return 443; @@ -277,6 +278,7 @@ export class BigQueryStorageClient { /** * The scopes needed to make gRPC calls for every method defined * in this service. + * @returns {string[]} List of default scopes. */ static get scopes() { return [ @@ -290,8 +292,7 @@ export class BigQueryStorageClient { 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 @@ -383,7 +384,11 @@ export class BigQueryStorageClient { * 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 [ReadSession]{@link google.cloud.bigquery.storage.v1beta1.ReadSession}. - * 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.createReadSession(request); */ createReadSession( request: protos.google.cloud.bigquery.storage.v1beta1.ICreateReadSessionRequest, @@ -485,7 +490,11 @@ export class BigQueryStorageClient { * 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 [BatchCreateReadSessionStreamsResponse]{@link google.cloud.bigquery.storage.v1beta1.BatchCreateReadSessionStreamsResponse}. - * 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.batchCreateReadSessionStreams(request); */ batchCreateReadSessionStreams( request: protos.google.cloud.bigquery.storage.v1beta1.IBatchCreateReadSessionStreamsRequest, @@ -596,7 +605,11 @@ export class BigQueryStorageClient { * 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.finalizeStream(request); */ finalizeStream( request: protos.google.cloud.bigquery.storage.v1beta1.IFinalizeStreamRequest, @@ -710,7 +723,11 @@ export class BigQueryStorageClient { * 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 [SplitReadStreamResponse]{@link google.cloud.bigquery.storage.v1beta1.SplitReadStreamResponse}. - * 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.splitReadStream(request); */ splitReadStream( request: protos.google.cloud.bigquery.storage.v1beta1.ISplitReadStreamRequest, @@ -781,6 +798,13 @@ export class BigQueryStorageClient { * 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 [ReadRowsResponse]{@link google.cloud.bigquery.storage.v1beta1.ReadRowsResponse} on 'data' event. + * Please see the + * [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#server-streaming) + * for more details and examples. + * @example + * const stream = client.readRows(request); + * stream.on('data', (response) => { ... }); + * stream.on('end', () => { ... }); */ readRows( request?: protos.google.cloud.bigquery.storage.v1beta1.IReadRowsRequest, @@ -928,9 +952,10 @@ export class BigQueryStorageClient { } /** - * 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-bigquery-storage/synth.metadata b/packages/google-cloud-bigquery-storage/synth.metadata index 08f1c1064e3..45b45bd4e5f 100644 --- a/packages/google-cloud-bigquery-storage/synth.metadata +++ b/packages/google-cloud-bigquery-storage/synth.metadata @@ -3,23 +3,15 @@ { "git": { "name": ".", - "remote": "https://github.com/googleapis/nodejs-bigquery-storage.git", - "sha": "10c93ec771f1715a8f97dde1840ed5071275bec8" - } - }, - { - "git": { - "name": "googleapis", - "remote": "https://github.com/googleapis/googleapis.git", - "sha": "4c5071b615d96ef9dfd6a63d8429090f1f2872bb", - "internalRef": "327369997" + "remote": "git@github.com:googleapis/nodejs-bigquery-storage.git", + "sha": "9b828c649de99a96418c1d580c6440016aa298a3" } }, { "git": { "name": "synthtool", "remote": "https://github.com/googleapis/synthtool.git", - "sha": "ba9918cd22874245b55734f57470c719b577e591" + "sha": "1f1148d3c7a7a52f0c98077f976bd9b3c948ee2b" } } ], @@ -96,6 +88,7 @@ "README.md", "api-extractor.json", "linkinator.config.json", + "package-lock.json.1985761200", "protos/google/cloud/bigquery/storage/v1/arrow.proto", "protos/google/cloud/bigquery/storage/v1/avro.proto", "protos/google/cloud/bigquery/storage/v1/storage.proto", @@ -110,6 +103,7 @@ "protos/protos.json", "renovate.json", "samples/README.md", + "samples/package-lock.json.1553614215", "src/v1/big_query_read_client.ts", "src/v1/big_query_read_client_config.json", "src/v1/big_query_read_proto_list.json", diff --git a/packages/google-cloud-bigquery-storage/system-test/fixtures/sample/src/index.ts b/packages/google-cloud-bigquery-storage/system-test/fixtures/sample/src/index.ts index 5edf8f362ab..f6f97a14228 100644 --- a/packages/google-cloud-bigquery-storage/system-test/fixtures/sample/src/index.ts +++ b/packages/google-cloud-bigquery-storage/system-test/fixtures/sample/src/index.ts @@ -18,8 +18,15 @@ import {BigQueryReadClient} from '@google-cloud/bigquery-storage'; +// check that the client class type name can be used +function doStuffWithBigQueryReadClient(client: BigQueryReadClient) { + client.close(); +} + function main() { - new BigQueryReadClient(); + // check that the client instance can be created + const bigQueryReadClient = new BigQueryReadClient(); + doStuffWithBigQueryReadClient(bigQueryReadClient); } main(); diff --git a/packages/google-cloud-bigquery-storage/system-test/install.ts b/packages/google-cloud-bigquery-storage/system-test/install.ts index 4c1ba3eb79a..39d90f771de 100644 --- a/packages/google-cloud-bigquery-storage/system-test/install.ts +++ b/packages/google-cloud-bigquery-storage/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); }); });