promise array results

[callmehiphop]

The age old question - why do Promises always resolve with tuples (Arrays)?

There have been a few threads where we receive complaints about Promises resolving with tuples. More often than not the suggestion to resolve with objects is made, but personally I don't see why we would want to do that. With destructuring the end result is the same and tuples are slightly easier to work with.

My overall opinion is that if we want to do away with tuples, we should change all methods to not return the response and if there are use cases for the raw response data, we create an alternate version of the method that exposes it in some way. For some types of methods this is pretty easy, but with others not so much. Here's a possible solution for the various types of methods we have

resource creators

For resource creating methods I think it would be safe to just drop the response completely since it always gets set as the metadata property.

Before

const [bucket, apiResponse] = await storage.createBucket('my-bucket');

After

const bucket = await storage.createBucket('my-bucket');
const apiResponse = bucket.metadata; // if the user wants it

paginated lasts

For paginated lists I think we should split up the functionality into 2 separate methods.

• a method for returning all resources (autoPaginate: true)
• a method that returns a single page of resources (autoPaginate: false)

This has an added benefit of following the single responsibility principle since the current version changes the response tuple based on an option.

Before

const [buckets] = await storage.getBuckets();
// or
const [buckets, nextQuery, response] = await storage.getBuckets({autoPaginate: false});

After

type BucketList = Array<Bucket>;

interface BucketPage extends BucketList {
  nextQuery?: GetBucketsRequest;
  apiResponse: ListBucketsResponse
}

const buckets: BucketList = await storage.getAllBuckets();
// or
const buckets: BucketPage = await storage.getBuckets();
const {nextQuery, apiResponse} = buckets;

convenience methods

We have several convenience methods that essentially wrap other methods (exists -> getMetadata). I think we should ditch the response on these kinds of methods and add JSDoc {@link} tags to whatever is called under the hood.

Before

const [exists] = await bucket.exists();
if (exists) doSomething();

After

if (await bucket.exists()) doSomething();

operation methods

For resources that require a lro we should separate that logic into 2 different methods (BigQuery already does this).

• a method for creating the operation
• a method that creates an operation under the hood and taps into 'complete' to return the requested resource.

Since we would be returning 2 resources, each response would be available via metadata property.

Before

const [operation, instance] = await spanner.createInstance(instanceConfig);
await operation.promise();
// `instance` is ready to use

After

const operation = await spanner.createInstanceJob(instanceConfig);
const instance = await operation.promise();

// or
const instance = await spanner.createInstance(instanceConfig);

queries

Methods that perform a query often contain both data and statistics about the query itself. Unlike paginated lists, I feel like this information should always be returned.

Before

const [rows, stats] = await transaction.run('SELECT * FROM `MyTable`');

After

interface RowList extends Array<Row> {
  stats: RowStats
}

const rows: RowList = await transaction.run('SELECT * FROM `MyTable`');
const {stats} = rows;

[JustinBeckwith]

For housekeeping purposes - should we combine this with #2556? Not sure which one to keep since you have all this lovely detail here :)

[bcoe]

We haven't had many customer complaints about this issue in recent years. I'm of the opinion that array destructuring + fairly good sample coverage, has made the design decision of returning a tuple not too disruptive.

[callmehiphop]

I'm about to get the best sleep of my life tonight

…

On Mon, Jul 4, 2022, 1:27 PM Benjamin E. Coe ***@***.***> wrote: We haven't had many customer complaints about this issue in recent years. I'm of the opinion that array destructuring + fairly good sample coverage, has made the design decision of returning a tuple not *too* disruptive. — Reply to this email directly, view it on GitHub <#2896 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AANA2A64K3CWICIIBQKDRPTVSMNHHANCNFSM4GRWBINA> . You are receiving this because you authored the thread.Message ID: ***@***.***>