NodeJS Datastore Transaction - .run() is confusing

[Kaan]

The docs here use .run() - more like a .start()-like command: https://cloud.google.com/datastore/docs/concepts/transactions

However the direct reference: https://googleapis.dev/nodejs/datastore/latest/Transaction.html#run

Uses .run(function(){ DO_THINGS_HERE_THEN_COMMIT }); kinda way

So basically the App Engine examples use .run() like a formality, they just call transaction's get methods etc. afterwards - but the direct docs suggest everything to be inside .run()

Question:  I'm guessing .run() is like a formality that starts a transaction, the transaction.get()'s etc. lock entities, and if they are modified outside, transaction fails? - so basically, instead of a formality .run() - the other transaction commands could've internally done this too

And I also guess retries aren't a thing any more, so using .run() like a formality goes - however, if the default approach was to put everything inside the run()'s callback function, couldn't there be a retry parameter too?

[Kaan]

Another confusing matter, do we .rollback() explicitly, even if the exception is from the .commit() - I guess so - honestly they all make up a huge code mess, it could've been simpler if the transaction routines were actually transaction routines and these were automated? I guess one could also easily write wrappers that do this

So my point is, I guess it's not a transaction system exactly, but more like a lock, lock-check, lock-release system - correct me if I missed anything

[Kaan]

I have to say the NodeJS Datastore methods is really not well thought, at all - they are almost sadistic in nature

.get() doesn't have a sync option, which is perfectly okay at this point in time, almost all functions need to be async, might as well await

However, what is not okay is that, it returns an array with only one entity, even if you provide a single key to it

So you always have to:

```

var entity=await datastore.get(datastore.key(["Name","key"]));

if(entity) entity=entity[0];

```

The natural response is to return a singular entity, not an array with one entity

All the Python API's up to this point has been like this too, so the expected response is this also

At every point, I stop and ask

[Elliott (Cloud Platform Support)]

Hello,

Thank you for your question. I understand correctly, you would like to point out that there is a differing programming style between the two documents and you would like clarification on the examples provided.

The best way to move forward is to create an issue on Github here that will be addressed by the specialists. They deal with questions like yours and may guide you. I understand your frustration on this.

[Kaan]

My latest frustration: https://github.com/googleapis/nodejs-datastore/issues/783

Undocumented transaction.get() and unexpected behaviour

[Elliott (Cloud Platform Support)]

Hello,

I understand that the transaction.get() method is buggy and it doesn’t have the documentation you need to productively use the API. It can be frustrating when something like this happens. But you’ve posted your concerns in the right place on github and the API team will certainly help you. We take the community’s feedback seriously and will take a course of action to get this sorted out for you. Again, thank you for your feedback because we use it to improve the quality of our products to the benefit of the community. If you have any more concerns, please let us know and we will gladly assist you then.

I hope this helps.