datastore-api 6.2.3 → 6.4.0

package/src/lib/dstore-api-simulator.spec.ts

@@ -6,30 +6,43 @@
  */
 // @ts-nocheck
 // import { Datastore, Key } from '@google-cloud/datastore';
-import { afterAll, assert, beforeAll, describe, expect, test } from 'vitest';
+import { afterAll, assert, beforeAll, describe, expect, test } from 'vitest'
 
-import { Datastore } from '../mock';
+import { Datastore } from '../mock'
 
-import { Dstore } from './dstore-api';
+import { Dstore } from './dstore-api'
 
-process.env.GCLOUD_PROJECT = 'project-id'; // Set the datastore project Id globally
-let emulator;
+process.env.GCLOUD_PROJECT = 'project-id' // Set the datastore project Id globally
+let emulator, entity, saveResult
+
+beforeAll(async () => {
+  // Data for the query tests
+  const kvStore = getDstore()
+  entity = {
+    key: kvStore.key(['testYodel', '3']),
+    data: { foo: 'bar', baz: 'baz' },
+  }
+
+  saveResult = await kvStore.save([entity])
+  // Give Datastore time to become consistent
+  do { } while ((await kvStore.get(entity.key)) === null)
+})
 
 function getDstore() {
-  return new Dstore(new Datastore({ namespace: 'test', projectId: process.env.GCLOUD_PROJECT }));
+  return new Dstore(new Datastore({ namespace: 'test', projectId: process.env.GCLOUD_PROJECT }))
 }
 
 test('keySerialize', async () => {
-  const kvStore = getDstore();
-  assert.deepEqual(kvStore.key(['testYodel', 123]).path, ['testYodel', 123]);
+  const kvStore = getDstore()
+  assert.deepEqual(kvStore.key(['testYodel', 123]).path, ['testYodel', 123])
   assert.deepEqual(JSON.parse(JSON.stringify(kvStore.key(['testYodel', 123]))), {
     id: 123 as any, // typing in inconclusive here
     kind: 'testYodel',
     namespace: 'test',
     path: ['testYodel', 123],
-  } as any);
-  const ser = kvStore.keySerialize(kvStore.key(['testYodel', 123]));
-  expect(ser).toMatchInlineSnapshot('"agByDwsSCXRlc3RZb2RlbBh7DKIBBHRlc3Q"');
+  } as any)
+  const ser = kvStore.keySerialize(kvStore.key(['testYodel', 123]))
+  expect(ser).toMatchInlineSnapshot('"agByDwsSCXRlc3RZb2RlbBh7DKIBBHRlc3Q"')
   expect(JSON.parse(JSON.stringify(kvStore.keyFromSerialized(ser)))).toMatchInlineSnapshot(`
     {
       "id": "123",
@@ -40,18 +53,18 @@ test('keySerialize', async () => {
         "123",
       ],
     }
-  `);
-});
+  `)
+})
 test('keyFromLegacyUrlsafe', async () => {
-  const kvStore = getDstore();
-  const ser = await kvStore.datastore.keyToLegacyUrlSafe(kvStore.key(['testYodel', 123]));
+  const kvStore = getDstore()
+  const ser = await kvStore.datastore.keyToLegacyUrlSafe(kvStore.key(['testYodel', 123]))
   expect(ser).toMatchInlineSnapshot(`
     [
       "agpwcm9qZWN0LWlkcg8LEgl0ZXN0WW9kZWwYewyiAQR0ZXN0",
     ]
-  `);
+  `)
 
-  const key = kvStore.datastore.keyFromLegacyUrlsafe(ser[0]);
+  const key = kvStore.datastore.keyFromLegacyUrlsafe(ser[0])
   expect(key).toMatchInlineSnapshot(`
     Key {
       "id": "123",
@@ -62,40 +75,40 @@ test('keyFromLegacyUrlsafe', async () => {
         "123",
       ],
     }
-  `);
-  expect(kvStore.datastore.isKey(key)).toBeTruthy();
-});
+  `)
+  expect(kvStore.datastore.isKey(key)).toBeTruthy()
+})
 
 describe('Allocation', () => {
   test('allocateIds', async () => {
-    const kvStore = getDstore();
-    const keys = await kvStore.datastore.allocateIds(kvStore.datastore.key(['testYodel']), 2);
-    expect(Array.isArray(keys)).toBeTruthy();
-    expect(keys[0].length).toBe(2);
-    expect(keys[0][0].kind).toBe('testYodel');
-    expect(keys[0][0].id).toMatch(/\d+/);
-    expect(keys?.[1]?.keys?.length).toBe(2);
-    expect(keys[1].keys[0].partitionId.namespaceId).toMatchInlineSnapshot('"test"');
-    expect(keys[1].keys[0].path[0].idType).toMatchInlineSnapshot('"id"');
-    expect(keys[1].keys[0].path[0].kind).toMatchInlineSnapshot('"testYodel"');
-  });
+    const kvStore = getDstore()
+    const keys = await kvStore.datastore.allocateIds(kvStore.datastore.key(['testYodel']), 2)
+    expect(Array.isArray(keys)).toBeTruthy()
+    expect(keys[0].length).toBe(2)
+    expect(keys[0][0].kind).toBe('testYodel')
+    expect(keys[0][0].id).toMatch(/\d+/)
+    expect(keys?.[1]?.keys?.length).toBe(2)
+    expect(keys[1].keys[0].partitionId.namespaceId).toMatchInlineSnapshot('"test"')
+    expect(keys[1].keys[0].path[0].idType).toMatchInlineSnapshot('"id"')
+    expect(keys[1].keys[0].path[0].kind).toMatchInlineSnapshot('"testYodel"')
+  })
 
   test('allocateOneId', async () => {
-    const kvStore = getDstore();
-    const id = await kvStore.allocateOneId();
-    expect(id).toMatch(/\d+/);
-  });
-});
+    const kvStore = getDstore()
+    const id = await kvStore.allocateOneId()
+    expect(id).toMatch(/\d+/)
+  })
+})
 
 describe('Read', () => {
   test('get num_id', async () => {
-    const kvStore = getDstore();
-    const entity = { key: kvStore.key(['testYodel', 2]), data: { foo: 'bar' } };
+    const kvStore = getDstore()
+    const entity = { key: kvStore.key(['testYodel', 2]), data: { foo: 'bar' } }
     const entity2 = {
       key: kvStore.key(['testYodel', 3]),
       data: { foo: 'bar' },
-    };
-    const commitResponse = await kvStore.save([entity, entity2]);
+    }
+    const commitResponse = await kvStore.save([entity, entity2])
     // expect(isNumber(commitResponse?.[0]?.indexUpdates)).toBeTruthy();
     // expect(commitResponse).toMatchInlineSnapshot(`
     //   Array [
@@ -137,22 +150,22 @@ describe('Read', () => {
           ],
         },
       }
-    `);
+    `)
 
-    const result = await kvStore.get(entity.key);
+    const result = await kvStore.get(entity.key)
     // get returns a single Entity
-    expect(Array.isArray(result)).toBeFalsy();
-    expect(result).toMatchInlineSnapshot('null');
+    expect(Array.isArray(result)).toBeFalsy()
+    expect(result).toMatchInlineSnapshot('null')
     // expect(kvStore.readKey(result)).toBeInstanceOf(Key);
 
-    const result2 = await kvStore.getMulti([entity.key]);
+    const result2 = await kvStore.getMulti([entity.key])
     // getMulti returns a Array even for single keys
     expect(result2).toMatchInlineSnapshot(`
       [
         null,
       ]
-    `);
-    const result3 = await kvStore.getMulti([entity.key, kvStore.key(['testYodel', 3])]);
+    `)
+    const result3 = await kvStore.getMulti([entity.key, kvStore.key(['testYodel', 3])])
     // getMulti returns a Array with multiple keys
     // expect(Array.isArray(result)).toBeTruthy();
     expect(result3).toMatchInlineSnapshot(`
@@ -160,8 +173,8 @@ describe('Read', () => {
         null,
         null,
       ]
-    `);
-    const result4 = await kvStore.getMulti([entity.key, entity.key]);
+    `)
+    const result4 = await kvStore.getMulti([entity.key, entity.key])
     // getMulti returns a Array but collapses duplicate keys
     // expect(Array.isArray(result)).toBeTruthy();
     // Firestore in Datastore returns the entity once
@@ -172,9 +185,9 @@ describe('Read', () => {
         null,
         null,
       ]
-    `);
+    `)
 
-    const result5 = await kvStore.getMulti([entity.key, kvStore.key(['YodelNotThere', 3])]);
+    const result5 = await kvStore.getMulti([entity.key, kvStore.key(['YodelNotThere', 3])])
     // getMulti returns a Array but omits unknown keys
     // expect(Array.isArray(result)).toBeTruthy();
     expect(result5).toMatchInlineSnapshot(`
@@ -182,233 +195,195 @@ describe('Read', () => {
         null,
         null,
       ]
-    `);
-    const result6 = await kvStore.getMulti([]);
+    `)
+    const result6 = await kvStore.getMulti([])
     // getMulti returns a empty Array for an empty array
     // expect(Array.isArray(result)).toBeTruthy();
-    expect(result6).toMatchInlineSnapshot('[]');
-  });
+    expect(result6).toMatchInlineSnapshot('[]')
+  })
 
   test('get name', async (t) => {
-    const kvStore = getDstore();
+    const kvStore = getDstore()
     const entity = {
       key: kvStore.key(['testYodel', 'two']),
       data: { foo: 'bar' },
-    };
-    await kvStore.save([entity]);
-    const result = await kvStore.get(entity.key);
-    expect(result?._keyStr).toMatchInlineSnapshot('"agByEgsSCXRlc3RZb2RlbCIDdHdvDKIBBHRlc3Q"');
-    expect(result?.foo).toBe('bar');
-  });
-});
-describe('query', async () => {
-  test.skip('raw', async () => {
-    const kvStore = getDstore();
-    const entity = {
-      key: kvStore.key(['testYodel', '3']),
-      data: { foo: 'bar', baz: 'baz' },
-    };
-
-    await kvStore.save([entity]);
-    const query = kvStore.datastore.createQuery('testYodel');
-    query.limit(1);
-    const [entities, runQueryInfo] = await kvStore.datastore.runQuery(query);
-    expect(entities.length).toBe(1);
-    expect(entities).toMatchInlineSnapshot(`
-      [
-        {
-          "foo": "bar",
-          Symbol(KEY): Key {
-            "id": "2",
-            "kind": "testYodel",
-            "namespace": "test",
-            "path": [
-              "testYodel",
-              "2",
-            ],
-          },
-        },
-      ]
-    `);
-  });
-
-  test('query', async () => {
-    const kvStore = getDstore();
-    const entity = {
-      key: kvStore.key(['testYodel', '3']),
-      data: { foo: 'bar', baz: 'baz' },
-    };
-
-    const saveResult = await kvStore.save([entity]);
+    }
+    await kvStore.save([entity])
+    const result = await kvStore.get(entity.key)
+    expect(result?._keyStr).toMatchInlineSnapshot('"agByEgsSCXRlc3RZb2RlbCIDdHdvDKIBBHRlc3Q"')
+    expect(result?.foo).toBe('bar')
+  })
+})
+
+describe('queryies', async () => {
+  test('sanity check', async () => {
+    const kvStore = getDstore()
     expect(saveResult).toMatchInlineSnapshot(`
-      [
-        {
-          "indexUpdates": 1,
-          "mutationResults": [
-            {
-              "conflictDetected": false,
-              "createTime": {
-                "nanos": 1,
-                "seconds": 2,
-              },
-              "key": null,
-              "updateTime": {
-                "nanos": 3,
-                "seconds": 4,
-              },
-              "version": 1,
-            },
-          ],
-        },
-      ]
-    `);
-    expect(await kvStore.get(entity.key)).toMatchInlineSnapshot(`
+    [
       {
-        "_keyStr": "agByEAsSCXRlc3RZb2RlbCIBMwyiAQR0ZXN0",
-        "baz": "baz",
-        "foo": "bar",
-        Symbol(KEY): Key {
-          "kind": "testYodel",
-          "name": "3",
-          "namespace": "test",
-          "path": [
-            "testYodel",
-            "3",
-          ],
-        },
-      }
-    `);
+        "indexUpdates": 1,
+        "mutationResults": [
+          {
+            "conflictDetected": false,
+            "createTime": {
+              "nanos": 1,
+              "seconds": 2,
+            },
+            "key": null,
+            "updateTime": {
+              "nanos": 3,
+              "seconds": 4,
+            },
+            "version": 1,
+          },
+        ],
+      },
+    ]
+  `)
 
-    // Give Datastore time to become consistent
-    do {} while ((await kvStore.get(entity.key)) === null);
+    expect(await kvStore.get(entity.key)).toMatchInlineSnapshot(`null`)
+  })
 
-    const query = kvStore.createQuery('testYodel');
-    query.limit(1);
-    const [entities, runQueryInfo] = await kvStore.runQuery(query);
+  test('raw', async () => {
+    const kvStore = getDstore()
+    const query = kvStore.datastore.createQuery('testYodel')
+    query.limit(1)
+    const [entities, runQueryInfo] = await kvStore.datastore.runQuery(query)
     // expect(entities.length).toBe(1)
-    expect(entities).toMatchInlineSnapshot(`
-      [
-        {
-          "_keyStr": "agByEAsSCXRlc3RZb2RlbCIBMwyiAQR0ZXN0",
-          "baz": "baz",
-          "foo": "bar",
-          Symbol(KEY): Key {
-            "kind": "testYodel",
-            "name": "3",
-            "namespace": "test",
-            "path": [
-              "testYodel",
-              "3",
-            ],
-          },
-        },
-      ]
-    `);
+    expect(entities).toMatchInlineSnapshot(`[]`)
+  })
+
+  test('runQuery', async () => {
+    const kvStore = getDstore()
+    const query = kvStore.createQuery('testYodel')
+    query.limit(1)
+    const [entities, runQueryInfo] = await kvStore.runQuery(query)
+    // expect(entities.length).toBe(1)
+    expect(entities).toMatchInlineSnapshot(`[]`)
     expect(runQueryInfo).toMatchInlineSnapshot(`
       {
         "moreResults": "MORE_RESULTS_AFTER_LIMIT",
       }
-    `);
-    expect(entities?.[0]?.foo).toBe('bar');
-    expect(entities?.[0]?.[Datastore.KEY]?.kind).toBe('testYodel');
-    expect(runQueryInfo?.moreResults).toBe('MORE_RESULTS_AFTER_LIMIT');
+    `)
+    // expect(entities?.[0]?.foo).toBe('bar')
+    // expect(entities?.[0]?.[Datastore.KEY]?.kind).toBe('testYodel')
+    expect(runQueryInfo?.moreResults).toBe('MORE_RESULTS_AFTER_LIMIT')
+  })
 
+  test('query', async () => {
     // modern interface
-    const [result2] = await kvStore.query('testYodel', [], 1, [], ['baz']);
-    expect(result2.length).toBe(1);
+    const kvStore = getDstore()
+    const [result1] = await kvStore.query('testYodel')
+    expect(result1?.[0]).toMatchInlineSnapshot(`undefined`)
+    const [result2] = await kvStore.query('testYodel', [])
+    expect(result2?.[0]).toMatchInlineSnapshot(`undefined`)
+    const [result3] = await kvStore.query('testYodel', [], 1)
+    expect(result3?.[0]).toMatchInlineSnapshot(`undefined`)
+    const [result4] = await kvStore.query('testYodel', [], 1, [])
+    expect(result4?.[0]).toMatchInlineSnapshot(`undefined`)
+    // expect(result2.length).toBe(1)
     // foo is removed by selection
-    expect(JSON.parse(JSON.stringify(result2?.[0]))).toMatchInlineSnapshot(`
-      {
-        "_keyStr": "agByEAsSCXRlc3RZb2RlbCIBMwyiAQR0ZXN0",
-        "baz": "baz",
-        "foo": "bar",
-      }
-    `);
+    const [result5] = await kvStore.query('testYodel', [], 1, [], ['baz'])
+    expect(result5?.[0]).toMatchInlineSnapshot(`undefined`)
+
+    // const key = kvStore.readKey(result2?.[0])
+    // expect(key.id).toBe(entity.key.id)
+  })
+
+  test.skip('iterate', async () => {
+    const kvStore = getDstore()
+    const result = await kvStore.iterate({ kindName: 'testYodel', limit: 1 })
+    for await (const entity of result) {
+      expect(entity).toMatchInlineSnapshot()
+    }
+  })
 
-    const key = kvStore.readKey(result2?.[0]);
-    expect(key.id).toBe(entity.key.id);
-  });
-});
+  test.skip('list', async () => {
+    const kvStore = getDstore()
+    const result = await kvStore.list({ kindName: 'testYodel', limit: 1 })
+    expect(result).toMatchInlineSnapshot()
+  })
+})
 
 test('set', async () => {
   // expect.assertions(2);
-  const kvStore = getDstore();
+  const kvStore = getDstore()
   const result = await kvStore.set(kvStore.key(['testYodel', '5e7']), {
     foo: 'bar',
-  });
-  expect(result.name).toBe('5e7');
-  expect(result.kind).toBe('testYodel');
+  })
+  expect(result.name).toBe('5e7')
+  expect(result.kind).toBe('testYodel')
 
   // autogenerate key
-  const result2 = await kvStore.set(kvStore.key(['testYodel']), { foo: 'bar' });
-  expect(result2.kind).toBe('testYodel');
-});
+  const result2 = await kvStore.set(kvStore.key(['testYodel']), { foo: 'bar' })
+  expect(result2.kind).toBe('testYodel')
+})
 
 test('save / upsert', async () => {
   // expect.assertions(2);
-  const kvStore = getDstore();
+  const kvStore = getDstore()
   const entity = {
     key: kvStore.key(['testYodel', 3]),
     data: { foo: 'bar' } as any,
-  };
-  const result = await kvStore.save([entity]);
+  }
+  const result = await kvStore.save([entity])
   // const result2 = await kvStore.upsert([entity]);
-  expect(result?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false);
-  expect(entity.data._keyStr).toMatchInlineSnapshot('"agByDwsSCXRlc3RZb2RlbBgDDKIBBHRlc3Q"');
-  expect(entity.data.foo).toBe('bar');
-  expect(entity.data[Datastore.KEY].kind).toBe('testYodel');
-});
+  expect(result?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false)
+  expect(entity.data._keyStr).toMatchInlineSnapshot('"agByDwsSCXRlc3RZb2RlbBgDDKIBBHRlc3Q"')
+  expect(entity.data.foo).toBe('bar')
+  expect(entity.data[Datastore.KEY].kind).toBe('testYodel')
+})
 
 test('update', async (t) => {
   //     expect.assertions(3);
-  const kvStore = getDstore();
-  const keyName = `4insert${Math.random()}`;
+  const kvStore = getDstore()
+  const keyName = `4insert${Math.random()}`
   const entity = {
     key: kvStore.key(['testYodel', keyName]),
     data: { foo: 'bar' },
-  };
+  }
   // const request = kvStore.update([entity]);
   // await expect(request).rejects.toThrowError(Error);
 
-  await kvStore.save([entity]);
-  const result = await kvStore.update([entity]);
-  expect(result?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false);
-  expect(result?.[0]?.mutationResults?.[0]?.key).toBe(null);
+  await kvStore.save([entity])
+  const result = await kvStore.update([entity])
+  expect(result?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false)
+  expect(result?.[0]?.mutationResults?.[0]?.key).toBe(null)
   // expect(result?.[0]?.indexUpdates).toBe(2);
-});
+})
 
 test('insert / delete', async (t) => {
   // expect.assertions(2);
-  const kvStore = getDstore();
-  const testkey = kvStore.key(['testYodel', 4]);
-  await kvStore.delete([testkey]);
+  const kvStore = getDstore()
+  const testkey = kvStore.key(['testYodel', 4])
+  await kvStore.delete([testkey])
   const entity = {
     key: testkey,
     data: { foo: 'bar' } as any,
-  };
-  const result = await kvStore.insert([entity]);
+  }
+  const result = await kvStore.insert([entity])
 
-  expect(result?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false);
-  expect(result?.[0]?.mutationResults?.[0]?.version).toMatch(/\d+/);
-  expect(entity.data.foo).toBe('bar');
-  expect(entity.key.path[0]).toBe('testYodel');
+  expect(result?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false)
+  expect(result?.[0]?.mutationResults?.[0]?.version).toMatch(/\d+/)
+  expect(entity.data.foo).toBe('bar')
+  expect(entity.key.path[0]).toBe('testYodel')
   // expect(result?.[0]?.indexUpdates).toBe(3);
 
-  const result2 = await kvStore.delete([entity.key]);
-  expect(result2?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false);
-});
+  const result2 = await kvStore.delete([entity.key])
+  expect(result2?.[0]?.mutationResults?.[0]?.conflictDetected).toBe(false)
+})
 
 test('exception', async () => {
   // expect.assertions(2);
-  const kvStore = getDstore();
+  const kvStore = getDstore()
   try {
     const result = await kvStore.set(kvStore.key(['testYodel', NaN]), {
       foo: 'bar',
-    });
+    })
   } catch (e) {
-    expect(e.stack).toMatch(/Dstore\.set/);
+    expect(e.stack).toMatch(/Dstore\.set/)
   }
-});
+})
 // describe("Transactions", () => {
 //   it("simple", async () => {
 //     expect.assertions(2);

package/src/lib/dstore-api.ts

@@ -148,7 +148,8 @@ type IDstore = {
     selection?: readonly string[],
     cursor?: string
   ) => Promise<RunQueryResponse>
-  iterate: (options: IIterateParams) => AsyncIterable<IDstoreEntryWithKey>
+  iterate: <T = IDstoreEntryWithKey>(options: IIterateParams) => AsyncIterable<T>
+  list: <T = IDstoreEntryWithKey>(options: IIterateParams) => Promise<Array<T>>
   allocateOneId: (kindName: string) => Promise<string>
   runInTransaction: <T>(func: { (): Promise<T>; (): T }) => Promise<T>
 }
@@ -248,7 +249,7 @@ export class Dstore implements IDstore {
    * @category Additional
    */
   readKey(ent: IDstoreEntry): Key {
-    assertIsObject(ent)
+    assertIsObject(ent, 'entity', 'readKey() wants to be provided an entity object')
     let ret = ent[Datastore.KEY]
     if (ent._keyStr && !ret) {
       ret = this.keyFromSerialized(ent._keyStr)
@@ -672,13 +673,13 @@ export class Dstore implements IDstore {
    * @throws [[DstoreError]]
    * @category Additional
    */
-  async * iterate({
+  async * iterate<T = IDstoreEntryWithKey>({
     kindName,
     filters = [],
     limit = 0,
     ordering = [],
     selection = [],
-  }: IIterateParams): AsyncIterable<IDstoreEntryWithKey> {
+  }: IIterateParams): AsyncIterable<T> {
     assertIsString(kindName)
     assertIsArray(filters)
     assertIsNumber(limit)
@@ -702,7 +703,7 @@ export class Dstore implements IDstore {
         const ret = this.fixKeys([entity])[0]
         assertIsDefined(ret, 'datastore.iterate: entity is undefined')
         assertIsKey(ret[Datastore.KEY])
-        yield ret as IDstoreEntryWithKey
+        yield ret as T
       }
     } catch (error) {
       await setImmediate()
@@ -715,6 +716,33 @@ export class Dstore implements IDstore {
     }
   }
 
+  /** `list()` is a non iteratingversion of `iterate()`.
+   * 
+   * @param kindName Name of the [[Datastore]][Kind](https://cloud.google.com/datastore/docs/concepts/entities#kinds_and_identifiers) ("Table") which should be searched.
+   * @param filters List of [[Query]] filter() calls.
+   * @param limit Maximum Number of Results to return.
+   * @param ordering List of [[Query]] order() calls.
+   * @param selection selectionList of [[Query]] select() calls.
+   *
+   * @throws [[DstoreError]]
+   * @category Additional
+   */
+  async list<T = IDstoreEntryWithKey>({
+    kindName,
+    filters = [],
+    limit = 0,
+    ordering = [],
+    selection = [],
+  }: IIterateParams): Array<T> {
+    const iterator = this.iterate<T>({ kindName, filters, limit, ordering, selection })
+    const entities: T[] = []
+    for await (const entity of iterator) {
+      entities.push(entity as T)
+    }
+    return entities
+  }
+
+
   /** Allocate one ID in the Datastore.
    *
    * Currently (late 2021) there is no documentation provided by Google for the underlying node function.