datastore-api 1.1.1 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.4.0](https://github.com/mdornseif/datastore-api/compare/v1.3.0...v1.4.0) (2022-01-04)
+
+
+### Features
+
+* save() adds _keyStr the same way get() does ([f4f6452](https://github.com/mdornseif/datastore-api/commit/f4f6452c77046c0ee8d0b6ddfe2ec6744a4968bd))
+
+## [1.3.0](https://github.com/mdornseif/datastore-api/compare/v1.2.0...v1.3.0) (2022-01-03)
+
+
+### Features
+
+* Set excludeLargeProperties by default. ([289cd28](https://github.com/mdornseif/datastore-api/commit/289cd289651b0c34f36098370b3dfbe249790c5a))
+
+## [1.2.0](https://github.com/mdornseif/datastore-api/compare/v1.1.3...v1.2.0) (2021-12-30)
+
+
+### Features
+
+* add `query(... selection)` ([e9f8053](https://github.com/mdornseif/datastore-api/commit/e9f8053fa98f496e69ccf83e649e7c1502751f16))
+* add KEYSYM ([d97eff0](https://github.com/mdornseif/datastore-api/commit/d97eff09f0c7dd60caa860eda45975438d369920))
+* debug log; removed readonly from several types ([f1fcdb6](https://github.com/mdornseif/datastore-api/commit/f1fcdb62551c3c624fcfd67f550f40a5bbd38138))
+
+### [1.1.3](https://github.com/mdornseif/datastore-api/compare/v1.1.2...v1.1.3) (2021-12-29)
+
+### [1.1.2](https://github.com/mdornseif/datastore-api/compare/v1.1.1...v1.1.2) (2021-12-29)
+
 ### [1.1.1](https://github.com/mdornseif/datastore-api/compare/v1.1.0...v1.1.1) (2021-12-29)
 
 ## [1.1.0](https://github.com/mdornseif/datastore-api/compare/v1.0.2...v1.1.0) (2021-12-25)

package/README.md

@@ -1,3 +1,7 @@
+[![version](https://img.shields.io/npm/v/datastore-api.svg?style=flat-square)](https://npmjs.org/datastore-api)
+[![license](https://img.shields.io/npm/l/datastore-api?color=%23007a1f&style=flat-square)](https://github.com/mdornseif/datastore-api/blob/master/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/datastore-api?style=flat-square&color=%23007a1f)](https://npmcharts.com/compare/datastore-api)
+
 # datastore-api
 
 Simplified, more consistent API for Google Cloud Datastore.
@@ -22,9 +26,9 @@ Main differences:
 
 Find the full documentation [here](http://mdornseif.io/datastore-api/classes/Dstore.html). In there also some of the idiosyncrasies of using the Datastore are explained.
 
-See [the API documentation](http://mdornseif.io/datastore-api/classes/Dstore.html) for Details.
+See [the API documentation](http://mdornseif.io/datastore-api/classes/Dstore.html) for Details, [Github](https://github.com/mdornseif/datastore-api) for source.
 
-# See also
+## See also
 
 - Google Documentation
 
@@ -33,7 +37,7 @@ See [the API documentation](http://mdornseif.io/datastore-api/classes/Dstore.htm
   - Other [Hidden Auto-Generated Datastore API Documentation](https://googleapis.dev/nodejs/datastore/latest/) with better navigation. Seems to contain more on the lower level access.
   - [SDK Source](https://github.com/googleapis/nodejs-datastore)
   - [API reference](https://cloud.google.com/datastore/docs/reference/data/rpc) helps to understand under-documented SDK.
-  - [grpc-js environment variables](https://github.com/grpc/grpc-node/blob/master/doc/environment_variables.md) - try[GRPC_VERBOSITY=DEBUG GRPC_TRACE=all yarn test](https://github.com/grpc/grpc-node/blob/master/TROUBLESHOOTING.md)
+  - [grpc-js environment variables](https://github.com/grpc/grpc-node/blob/master/doc/environment_variables.md) - try [GRPC_VERBOSITY=DEBUG GRPC_TRACE=all yarn test](https://github.com/grpc/grpc-node/blob/master/TROUBLESHOOTING.md)
 
 - API Simplification
   - [google-cloud-datastore-node](https://www.npmjs.com/package/google-cloud-datastore-node)

package/build/main/lib/dstore-api.d.ts

@@ -4,53 +4,61 @@ import { Operator, RunQueryResponse } from '@google-cloud/datastore/build/src/qu
 import { CommitResponse } from '@google-cloud/datastore/build/src/request';
 /** @ignore */
 export { Datastore, Key, PathType, Query, Transaction, } from '@google-cloud/datastore';
+export declare const KEYSYM: symbol;
 export declare type IGqlFilterTypes = boolean | string | number;
 export declare type IGqlFilterSpec = {
     readonly eq: IGqlFilterTypes;
 };
-export declare type TGqlFilterList = ReadonlyArray<readonly [string, Operator, DstorePropertyValues]>;
+export declare type TGqlFilterList = Array<[string, Operator, DstorePropertyValues]>;
 /** Define what can be written into the Datastore */
-export declare type DstorePropertyValues = number | string | Date | boolean | null | undefined | Buffer | Key | readonly DstorePropertyValues[] | {
-    readonly [key: string]: DstorePropertyValues;
+export declare type DstorePropertyValues = number | string | Date | boolean | null | undefined | Buffer | Key | DstorePropertyValues[] | {
+    [key: string]: DstorePropertyValues;
 };
+export interface IDstoreEntryWithoutKey {
+    /** All User Data stored in the Datastore */
+    [key: string]: DstorePropertyValues;
+}
 /** Represents what is actually stored inside the Datastore, called "Entity" by Google
     [@google-cloud/datastore](https://github.com/googleapis/nodejs-datastore#readme) adds `[Datastore.KEY]`. Using ES6 Symbols presents all kinds of hurdles, especially when you try to serialize into a cache. So we add the property _keyStr which contains the encoded code. It is automatically used
     to reconstruct `[Datastore.KEY]`, if you use [[Dstore.readKey]].
 */
-export declare type TDstoreEntry = {
+export interface IDstoreEntry extends IDstoreEntryWithoutKey {
     readonly [Datastore.KEY]?: Key;
     /** [Datastore.KEY] key */
     _keyStr: string;
     /** All User Data stored in the Datastore */
-    readonly [key: string]: DstorePropertyValues;
-};
+    [key: string]: DstorePropertyValues;
+}
 /** Represents the thing you pass to the save method. Also called "Entity" by Google */
 export declare type DstoreSaveEntity = {
-    readonly key: Key;
-    readonly data: Omit<TDstoreEntry, '_keyStr' | Datastore['KEY']>;
-    readonly method?: 'insert' | 'update' | 'upsert';
-    readonly excludeLargeProperties?: boolean;
-    readonly excludeFromIndexes?: readonly string[];
+    key: Key;
+    data: Omit<IDstoreEntry, '_keyStr' | Datastore['KEY']> & Partial<{
+        _keyStr: string;
+        [Datastore.KEY]: Key;
+    }>;
+    method?: 'insert' | 'update' | 'upsert';
+    excludeLargeProperties?: boolean;
+    excludeFromIndexes?: readonly string[];
 };
 declare type IDstore = {
     /** Accessible by Users of the library. Keep in mind that you will access outside transactions created by [[runInTransaction]]. */
     readonly datastore: Datastore;
-    readonly key: (path: ReadonlyArray<PathType>) => Key;
-    readonly keyFromSerialized: (text: string) => Key;
-    readonly keySerialize: (key: Key) => string;
-    readonly readKey: (entry: TDstoreEntry) => Key;
-    readonly get: (key: Key) => Promise<TDstoreEntry | null>;
-    readonly getMulti: (keys: ReadonlyArray<Key>) => Promise<ReadonlyArray<TDstoreEntry | undefined>>;
-    readonly set: (key: Key, entry: TDstoreEntry) => Promise<Key>;
-    readonly save: (entities: readonly DstoreSaveEntity[]) => Promise<CommitResponse | undefined>;
-    readonly insert: (entities: readonly DstoreSaveEntity[]) => Promise<CommitResponse | undefined>;
-    readonly update: (entities: readonly DstoreSaveEntity[]) => Promise<CommitResponse | undefined>;
-    readonly delete: (keys: readonly Key[]) => Promise<CommitResponse | undefined>;
-    readonly createQuery: (kind: string) => Query;
-    readonly query: (kind: string, filters?: TGqlFilterList, limit?: number, orders?: readonly string[]) => Promise<RunQueryResponse>;
-    readonly runQuery: (query: Query | Omit<Query, 'run'>) => Promise<RunQueryResponse>;
-    readonly allocateOneId: (kindName: string) => Promise<string>;
-    readonly runInTransaction: <T>(func: {
+    key: (path: ReadonlyArray<PathType>) => Key;
+    keyFromSerialized: (text: string) => Key;
+    keySerialize: (key: Key) => string;
+    readKey: (entry: IDstoreEntry) => Key;
+    get: (key: Key) => Promise<IDstoreEntry | null>;
+    getMulti: (keys: ReadonlyArray<Key>) => Promise<ReadonlyArray<IDstoreEntry | undefined>>;
+    set: (key: Key, entry: IDstoreEntry) => Promise<Key>;
+    save: (entities: readonly DstoreSaveEntity[]) => Promise<CommitResponse | undefined>;
+    insert: (entities: readonly DstoreSaveEntity[]) => Promise<CommitResponse | undefined>;
+    update: (entities: readonly DstoreSaveEntity[]) => Promise<CommitResponse | undefined>;
+    delete: (keys: readonly Key[]) => Promise<CommitResponse | undefined>;
+    createQuery: (kind: string) => Query;
+    query: (kind: string, filters?: TGqlFilterList, limit?: number, ordering?: readonly string[], selection?: readonly string[], cursor?: string) => Promise<RunQueryResponse>;
+    runQuery: (query: Query | Omit<Query, 'run'>) => Promise<RunQueryResponse>;
+    allocateOneId: (kindName: string) => Promise<string>;
+    runInTransaction: <T>(func: {
         (): Promise<T>;
         (): T;
     }) => Promise<T>;
@@ -60,18 +68,18 @@ declare type IDstore = {
 [@google-cloud/datastore](https://github.com/googleapis/nodejs-datastore#readme) is a strange beast: [The documentation is auto generated](https://cloud.google.com/nodejs/docs/reference/datastore/latest) and completely shy of documenting any advanced concepts.
 (Example: If you ask the datastore to auto-generate keys during save: how do you retrieve the generated key?) Generally I suggest to look at the Python 2.x [db](https://cloud.google.com/appengine/docs/standard/python/datastore/api-overview) and [ndb](https://cloud.google.com/appengine/docs/standard/python/ndb) documentation to get a better explanation of the workings of the datastore.
 
-Also the typings are strange. The Google provided type `Entities` can be the on disk representation, the same but including a key reference (`Datastore.KEY` - [[DstoreEntry]]), a list of these  or a structured object containing the on disk representation under the `data` property and a `key` property and maybe some configuration like `excludeFromIndexes` ([[DstoreSaveEntity]]) or a list of these.
+Also the typings are strange. The Google provided type `Entities` can be the on disk representation, the same but including a key reference (`Datastore.KEY` - [[IDstoreEntry]]), a list of these  or a structured object containing the on disk representation under the `data` property and a `key` property and maybe some configuration like `excludeFromIndexes` ([[DstoreSaveEntity]]) or a list of these.
 
 KvStore tries to abstract away most surprises the datastore provides to you but als tries to stay as API compatible as possible to [@google-cloud/datastore](https://github.com/googleapis/nodejs-datastore).
 
 Main differences:
 
 - Everything asynchronous is Promise-based - no callbacks.
-- [[get]] always returns a single [[DstoreEntry]].
-- [[getMulti]] always returns an Array<[[DstoreEntry]]> of the same length as the input Array. Items not found are represented by null.
+- [[get]] always returns a single [[IDstoreEntry]].
+- [[getMulti]] always returns an Array<[[IDstoreEntry]]> of the same length as the input Array. Items not found are represented by null.
 - [[set]] is called with `(key, value)` and always returns the complete [[Key]] of the entity being written. Keys are normalized, numeric IDs are always encoded as strings.
 - [[key]] handles [[Key]] object instantiation for you.
-- [[readKey]] extracts the key from an [[DstoreEntry]] you have read without the need of fancy `Symbol`-based access to `entity[Datastore.KEY]`. If needed, it tries to deserialize `_keyStr` to create `entity[Datastore.KEY]`. This ist important when rehydrating an [[DstoreEntry]] from a serializing cache.
+- [[readKey]] extracts the key from an [[IDstoreEntry]] you have read without the need of fancy `Symbol`-based access to `entity[Datastore.KEY]`. If needed, it tries to deserialize `_keyStr` to create `entity[Datastore.KEY]`. This ist important when rehydrating an [[IDstoreEntry]] from a serializing cache.
 - [[allocateOneId]] returns a single numeric string encoded unique datastore id without the need of fancy unpacking.
 - [[runInTransaction]] allows you to provide a function to be executed inside an transaction without the need of passing around the transaction object. This is modelled after Python 2.7 [ndb's `@ndb.transactional` feature](https://cloud.google.com/appengine/docs/standard/python/ndb/transactions). This is implemented via node's [AsyncLocalStorage](https://nodejs.org/docs/latest-v14.x/api/async_hooks.html).
 - [[keySerialize]] is synchronous.
@@ -126,24 +134,24 @@ export declare class Dstore implements IDstore {
      * @category Datastore Drop-In
      */
     keyFromSerialized(text: string): Key;
-    /** `readKey()` extracts the [[Key]] from an [[DstoreEntry]].
+    /** `readKey()` extracts the [[Key]] from an [[IDstoreEntry]].
      *
      * Is is an alternative to `entity[Datastore.KEY]` which tends to fail in various contexts and also confuses older Typescript compilers.
-     * It can extract the [[Key]] form a [[DstoreEntry]] which has been serialized to JSON by leveraging the property `_keyStr`.
+     * It can extract the [[Key]] form a [[IDstoreEntry]] which has been serialized to JSON by leveraging the property `_keyStr`.
      *
      * @category Additional
      */
-    readKey(ent: TDstoreEntry): Key;
-    /** `fixKeys()` is called for all [[DstoreEntry]]sa returned from [[Dstore]].
+    readKey(ent: IDstoreEntry): Key;
+    /** `fixKeys()` is called for all [[IDstoreEntry]]sa returned from [[Dstore]].
      *
      * Is ensures that besides `entity[Datastore.KEY]` there is `_keyStr` to be leveraged by [[readKey]].
      *
      * @internal
      */
     private fixKeys;
-    /** `get()` reads a [[DstoreEntry]] from the Datastore.
+    /** `get()` reads a [[IDstoreEntry]] from the Datastore.
      *
-     * It returns [[DstoreEntry]] or `null` if not found.
+     * It returns [[IDstoreEntry]] or `null` if not found.
   
      * The underlying Datastore API Call is [lookup](https://cloud.google.com/datastore/docs/reference/data/rest/v1/projects/lookup).
      *
@@ -152,14 +160,14 @@ export declare class Dstore implements IDstore {
      * Differences between [[Dstore.get]] and [[Datastore.get]]:
      *
      * - [Dstore.get]] takes a single [[Key]] as Parameter, no Array. Check [[getMulti]] if you want Arrays.
-     * - [Dstore.get]] returns a single [[DstoreEntry]], no Array.
+     * - [Dstore.get]] returns a single [[IDstoreEntry]], no Array.
      *
      * @category Datastore Drop-In
      */
-    get(key: Key): Promise<TDstoreEntry | null>;
-    /** `getMulti()` reads several [[DstoreEntry]]s from the Datastore.
+    get(key: Key): Promise<IDstoreEntry | null>;
+    /** `getMulti()` reads several [[IDstoreEntry]]s from the Datastore.
      *
-     * It returns a list of [[DstoreEntry]]s or `null` if not found.
+     * It returns a list of [[IDstoreEntry]]s or `null` if not found.
   
      * The underlying Datastore API Call is [lookup](https://cloud.google.com/datastore/docs/reference/data/rest/v1/projects/lookup).
      *
@@ -168,12 +176,12 @@ export declare class Dstore implements IDstore {
      * Differences between [[Dstore.getMulti]] and [[Datastore.get]]:
      *
      * - [[Dstore.getMulti]] always takes an Array of [[Key]]s as Parameter.
-     * - [[Dstore.getMulti]] returns always a Array of [[DstoreEntry]], or null.
+     * - [[Dstore.getMulti]] returns always a Array of [[IDstoreEntry]], or null.
      * - [[Datastore.get]] has many edge cases - e.g. when not being able to find any of the provided keys - which return surprising results. [[Dstore.getMulti]] always returns an Array. TODO: return a Array with the same length as the Input.
      *
      * @category Datastore Drop-In
      */
-    getMulti(keys: readonly Key[]): Promise<ReadonlyArray<TDstoreEntry | undefined>>;
+    getMulti(keys: readonly Key[]): Promise<Array<IDstoreEntry | undefined>>;
     /** `set()` is addition to [[Datastore]]. It provides a classic Key-value Interface.
      *
      * Instead providing a nested [[DstoreSaveEntity]] to [[save]] you can call set directly as `set( key, value)`.
@@ -190,7 +198,7 @@ export declare class Dstore implements IDstore {
      *
      * @category Additional
      */
-    set(key: Key, data: TDstoreEntry): Promise<Key>;
+    set(key: Key, data: IDstoreEntry): Promise<Key>;
     /** `save()` is compatible to [Datastore.save()](https://cloud.google.com/nodejs/docs/reference/datastore/latest/datastore/datastore#_google_cloud_datastore_Datastore_save_member_1_).
      *
      * The single Parameter is a list of [[DstoreSaveEntity]]s.
@@ -206,7 +214,21 @@ export declare class Dstore implements IDstore {
      *
      * If the Datastore generates a new ID because of an incomplete [[Key]] *on first save* it will return an large integer as [[Key.id]].
      * On every subsequent `save()` an string encoded number representation is returned.
-     * Dstore normalizes that and always returns an string encoded number representation.
+     * @todo Dstore should normalizes that and always return an string encoded number representation.
+     *
+     * Each [[DstoreSaveEntity]] can have an `excludeFromIndexes` property which is somewhat underdocumented.
+     * It can use something like JSON-Path notation
+     * ([Source](https://github.com/googleapis/nodejs-datastore/blob/2941f2f0f132b41534e303d441d837051ce88fd7/src/index.ts#L948))
+     * [.*](https://github.com/googleapis/nodejs-datastore/blob/406b15d2014087172df617c6e0a397a2c0902c5f/test/index.ts#L1598),
+     * [parent[]](https://github.com/googleapis/nodejs-datastore/blob/406b15d2014087172df617c6e0a397a2c0902c5f/test/index.ts#L1672),
+     * [parent.*](https://github.com/googleapis/nodejs-datastore/blob/406b15d2014087172df617c6e0a397a2c0902c5f/test/index.ts#L1672),
+     * [parent[].*](https://github.com/googleapis/nodejs-datastore/blob/406b15d2014087172df617c6e0a397a2c0902c5f/test/index.ts#L1672)
+     * and [more complex patterns](https://github.com/googleapis/nodejs-datastore/blob/406b15d2014087172df617c6e0a397a2c0902c5f/test/index.ts#L1754)
+     * seem to be supported patterns.
+     *
+     * If the caller has not provided an `excludeLargeProperties` in a [[DstoreSaveEntity]] we will default it
+     * to `excludeLargeProperties: true`. Without this you can not store strings longer than 1500 bytes easily
+     * ([source](https://github.com/googleapis/nodejs-datastore/blob/c7a08a8382c6706ccbfbbf77950babf40bac757c/src/entity.ts#L961)).
      *
      * @category Datastore Drop-In
      */
@@ -221,6 +243,8 @@ export declare class Dstore implements IDstore {
      *
      * For handling of incomplete [[Key]]s see [[save]].
      *
+     * This function can be completely emulated by using [[save]] with `method: 'insert'` inside each [[DstoreSaveEntity]].
+     *
      * @throws [[DstoreError]]
      * @category Datastore Drop-In
      */
@@ -235,15 +259,17 @@ export declare class Dstore implements IDstore {
      * It throws an [[DstoreError]] if there is no Entity with the same [[Key]] in the Datastore. `update()` *overwrites all existing data* for that [[Key]].
      * There was an alpha functionality called `merge()` in the Datastore which read an Entity, merged it with the new data and wrote it back, but this was never documented.
      *
-     * `update()` is idempotent. Deleting the same [[Key]] twice is no error.
+     * `update()` is idempotent. Updating the same [[Key]] twice is no error.
+     *
+     * This function can be completely emulated by using [[save]] with `method: 'update'` inside each [[DstoreSaveEntity]].
      *
      * @throws [[DstoreError]]
      * @category Datastore Drop-In
      */
     update(entities: readonly DstoreSaveEntity[]): Promise<CommitResponse | undefined>;
-    /** `delete()` is compatible to [Datastore.update()].
+    /** `delete()` is compatible to [Datastore.delete()].
      *
-     * Unfortunately currently (late 2021) there is no formal documentation from Google on [Datastore.update()].
+     * Unfortunately currently (late 2021) there is no formal documentation from Google on [Datastore.delete()].
      *
      * The single Parameter is a list of [[Key]]s.
      * If called within a transaction it returns `undefined`.
@@ -262,9 +288,10 @@ export declare class Dstore implements IDstore {
      * @param kind Name of the [[Datastore]][Kind](https://cloud.google.com/datastore/docs/concepts/entities#kinds_and_identifiers) ("Table") which should be searched.
      *
      * @category Datastore Drop-In
-     */ createQuery(kind: string): Query;
+     */
+    createQuery(kind: string): Query;
     runQuery(query: Query | Omit<Query, 'run'>): Promise<RunQueryResponse>;
-    query(kindName: string, filters?: TGqlFilterList, limit?: number, orders?: readonly string[]): Promise<RunQueryResponse>;
+    query(kindName: string, filters?: TGqlFilterList, limit?: number, ordering?: readonly string[], selection?: string[], cursor?: string): Promise<RunQueryResponse>;
     /** Allocate one ID in the Datastore.
      *
      * Currently (late 2021) there is no documentation provided by Google for the underlying node function.
@@ -279,16 +306,18 @@ export declare class Dstore implements IDstore {
     allocateOneId(kindName?: string): Promise<string>;
     /** This tries to give high level access to transactions.
   
-      Be aware that Transactions differ considerable between Master-Slave Datastore (very old), High Replication Datastore (old, later called [Google Cloud Datastore](https://cloud.google.com/datastore/docs/concepts/cloud-datastore-transactions)) and [Firestore in Datastore Mode](https://cloud.google.com/datastore/docs/firestore-or-datastore#in_datastore_mode) (current).
-  
       So called "Gross Group Transactions" are always enabled. Transactions are never Cross Project. `runInTransaction()` works only if you use the same [[KvStore] instance for all access within the Transaction.
   
       [[runInTransaction]] is modelled after Python 2.7 [ndb's `@ndb.transactional` feature](https://cloud.google.com/appengine/docs/standard/python/ndb/transactions). This is based on node's [AsyncLocalStorage](https://nodejs.org/docs/latest-v14.x/api/async_hooks.html).
   
-      Transactions frequently fail if you try to access the same data via in a transaction. See the [Documentation on Locking](https://cloud.google.com/datastore/docs/concepts/transactions#transaction_locks) for further reference. You are advised to use [p-limit](https://github.com/sindresorhus/p-limit)(1) to seralize transactions touching the same resource. This should work nicely with node's single process model. It is a much bigger problem on shared-nothing approaches, like Python on App Engine.
+      Transactions frequently fail if you try to access the same data via in a transaction. See the [Documentation on Locking](https://cloud.google.com/datastore/docs/concepts/transactions#transaction_locks) for further reference. You are advised to use [p-limit](https://github.com/sindresorhus/p-limit)(1) to serialize transactions touching the same resource. This should work nicely with node's single process model. It is a much bigger problem on shared-nothing approaches, like Python on App Engine.
   
       Transactions might be wrapped in [p-retry](https://github.com/sindresorhus/p-retry) to implement automatically retrying them with exponential back-off should they fail due to contention.
-     */
+  
+      Be aware that Transactions differ considerable between Master-Slave Datastore (very old), High Replication Datastore (old, later called [Google Cloud Datastore](https://cloud.google.com/datastore/docs/concepts/cloud-datastore-transactions)) and [Firestore in Datastore Mode](https://cloud.google.com/datastore/docs/firestore-or-datastore#in_datastore_mode) (current).
+  
+      Most Applications today are running on "Firestore in Datastore Mode". Beware that the Datastore-Emulator fails with `error: 3 INVALID_ARGUMENT: Only ancestor queries are allowed inside transactions.` during [[runQuery]] while the Datastore on Google Infrastructure does not have such an restriction anymore as of 2022.
+      */
     runInTransaction<T>(func: () => Promise<T>): Promise<T>;
 }
 export declare class DstoreError extends Error {