datastore-api 6.2.0 → 6.2.2

package/README.md

@@ -12,7 +12,7 @@ Dstore implements a slightly more accessible version of the [Google Cloud Datast
 
 Also the typings are strange and overly broad.
 
-Dstore 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).
+This package 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:
 
@@ -23,6 +23,7 @@ Main differences:
 - [allocateOneId](http://mdornseif.io/datastore-api/classes/Dstore.html#allocateOneId) returns a single numeric string encoded unique datastore id without the need of fancy unpacking.
 - [runInTransaction](http://mdornseif.io/datastore-api/classes/Dstore.html#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](http://mdornseif.io/datastore-api/classes/Dstore.html#keySerialize) is synchronous. 🦄
+- [iterate] allows for async iteration of (larege) queries.
 - Starting your code with the environment variable `DEBUG='ds:api'` allows you to trace API calls.
 
 Find the full documentation [here](https://mdornseif.github.io/datastore-api/classes/Dstore.html). In there also some of the idiosyncrasies of using the Datastore are explained.

package/dist/datastore-api.cjs.development.js

@@ -549,6 +549,35 @@ function _wrapNativeSuper(t) {
   }, _wrapNativeSuper(t);
 }
 
+/*
+ * assert.ts
+ *
+ * Created by Dr. Maximillian Dornseif 2025-04-11 in datastore-api 6.0.1
+ */
+/**
+ * Generates an type assertion message for the given `value`
+ *
+ * @param value value being type-checked
+ * @param type the expected value as a string; eg 'string', 'boolean', 'number'
+ * @param variableName the name of the variable being type-checked
+ * @param additionalMessage further information on failure
+ */
+var AssertionMessage = function AssertionMessage(value, type, variableName, additionalMessage) {
+  var message = variableName ? variableName + " must be of type '" + type + "', '" + assertateDebug.getType(value) + "' provided" : "expected value of type '" + type + "', '" + assertateDebug.getType(value) + "' provided";
+  return additionalMessage ? message + ": " + additionalMessage : message;
+};
+/**
+ * Type-checks the provided `value` to be a symbol, throws an Error if it is not
+ *
+ * @param value the value to type-check as a symbol
+ * @param variableName the name of the variable to be type-checked
+ * @param additionalMessage further information on failure
+ * @throws {Error}
+ */
+function assertIsKey(value, variableName, additionalMessage) {
+  assertateDebug.assert(datastore.Datastore.isKey(value), AssertionMessage(value, "Key", variableName, additionalMessage));
+}
+
 /** @ignore */
 var debug = /*#__PURE__*/Debug('ds:api');
 /** @ignore */
@@ -691,6 +720,31 @@ var Dstore = /*#__PURE__*/function () {
     });
     return entities;
   }
+  /** this is for save, insert, update and upsert  and ensures _kkeyStr() handling.
+   *
+   */;
+  _proto.prepareEntitiesForDatastore = function prepareEntitiesForDatastore(entities) {
+    for (var _iterator2 = _createForOfIteratorHelperLoose(entities), _step2; !(_step2 = _iterator2()).done;) {
+      var e = _step2.value;
+      assertateDebug.assertIsObject(e.key);
+      assertateDebug.assertIsObject(e.data);
+      this.fixKeys([e.data]);
+      e.excludeLargeProperties = e.excludeLargeProperties === undefined ? true : e.excludeLargeProperties;
+      e.data = _extends({}, e.data, {
+        _keyStr: undefined
+      });
+    }
+  }
+  /** this is for save, insert, update and upsert  and ensures _kkeyStr() handling.
+   *
+   */;
+  _proto.prepareEntitiesFromDatastore = function prepareEntitiesFromDatastore(entities) {
+    for (var _iterator3 = _createForOfIteratorHelperLoose(entities), _step3; !(_step3 = _iterator3()).done;) {
+      var e = _step3.value;
+      e.data[datastore.Datastore.KEY] = e.key;
+      this.fixKeys([e.data]);
+    }
+  }
   /** `get()` reads a [[IDstoreEntry]] from the Datastore.
    *
    * It returns [[IDstoreEntry]] or `null` if not found.
@@ -916,25 +970,16 @@ var Dstore = /*#__PURE__*/function () {
   /*#__PURE__*/
   function () {
     var _save = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regeneratorRuntime().mark(function _callee4(entities) {
-      var ret, metricEnd, _iterator2, _step2, e, _iterator3, _step3, _e;
+      var ret, metricEnd;
       return _regeneratorRuntime().wrap(function _callee4$(_context4) {
         while (1) switch (_context4.prev = _context4.next) {
           case 0:
             assertateDebug.assertIsArray(entities);
             metricEnd = metricHistogram.startTimer();
             _context4.prev = 2;
+            this.prepareEntitiesForDatastore(entities);
             // Within Transaction we don't get any answer here!
             // [ { mutationResults: [ [Object], [Object] ], indexUpdates: 51 } ]
-            for (_iterator2 = _createForOfIteratorHelperLoose(entities); !(_step2 = _iterator2()).done;) {
-              e = _step2.value;
-              assertateDebug.assertIsObject(e.key);
-              assertateDebug.assertIsObject(e.data);
-              this.fixKeys([e.data]);
-              e.excludeLargeProperties = e.excludeLargeProperties === undefined ? true : e.excludeLargeProperties;
-              e.data = _extends({}, e.data, {
-                _keyStr: undefined
-              });
-            }
             _context4.next = 6;
             return this.getDoT().save(entities);
           case 6:
@@ -946,11 +991,7 @@ var Dstore = /*#__PURE__*/function () {
             _context4.t0 = undefined;
           case 9:
             ret = _context4.t0;
-            for (_iterator3 = _createForOfIteratorHelperLoose(entities); !(_step3 = _iterator3()).done;) {
-              _e = _step3.value;
-              _e.data[datastore.Datastore.KEY] = _e.key;
-              this.fixKeys([_e.data]);
-            }
+            this.prepareEntitiesFromDatastore(entities);
             _context4.next = 19;
             break;
           case 13:
@@ -1012,43 +1053,45 @@ var Dstore = /*#__PURE__*/function () {
             assertateDebug.assertIsArray(entities);
             metricEnd = metricHistogram.startTimer();
             _context5.prev = 2;
-            _context5.next = 5;
+            this.prepareEntitiesForDatastore(entities);
+            _context5.next = 6;
             return this.getDoT().insert(entities);
-          case 5:
+          case 6:
             _context5.t0 = _context5.sent;
             if (_context5.t0) {
-              _context5.next = 8;
+              _context5.next = 9;
               break;
             }
             _context5.t0 = undefined;
-          case 8:
+          case 9:
             ret = _context5.t0;
-            _context5.next = 17;
+            this.prepareEntitiesFromDatastore(entities);
+            _context5.next = 19;
             break;
-          case 11:
-            _context5.prev = 11;
+          case 13:
+            _context5.prev = 13;
             _context5.t1 = _context5["catch"](2);
             // console.error(error)
             metricFailureCounter.inc({
               operation: 'insert'
             });
-            _context5.next = 16;
+            _context5.next = 18;
             return promises.setImmediate();
-          case 16:
+          case 18:
             throw new DstoreError('datastore.insert error', _context5.t1);
-          case 17:
-            _context5.prev = 17;
+          case 19:
+            _context5.prev = 19;
             metricEnd({
               operation: 'insert'
             });
-            return _context5.finish(17);
-          case 20:
+            return _context5.finish(19);
+          case 22:
             return _context5.abrupt("return", ret);
-          case 21:
+          case 23:
           case "end":
             return _context5.stop();
         }
-      }, _callee5, this, [[2, 11, 17, 20]]);
+      }, _callee5, this, [[2, 13, 19, 22]]);
     }));
     function insert(_x6) {
       return _insert.apply(this, arguments);
@@ -1090,43 +1133,45 @@ var Dstore = /*#__PURE__*/function () {
             });
             metricEnd = metricHistogram.startTimer();
             _context6.prev = 4;
-            _context6.next = 7;
+            this.prepareEntitiesForDatastore(entities);
+            _context6.next = 8;
             return this.getDoT().update(entities);
-          case 7:
+          case 8:
             _context6.t0 = _context6.sent;
             if (_context6.t0) {
-              _context6.next = 10;
+              _context6.next = 11;
               break;
             }
             _context6.t0 = undefined;
-          case 10:
+          case 11:
             ret = _context6.t0;
-            _context6.next = 19;
+            this.prepareEntitiesFromDatastore(entities);
+            _context6.next = 21;
             break;
-          case 13:
-            _context6.prev = 13;
+          case 15:
+            _context6.prev = 15;
             _context6.t1 = _context6["catch"](4);
             // console.error(error)
             metricFailureCounter.inc({
               operation: 'update'
             });
-            _context6.next = 18;
+            _context6.next = 20;
             return promises.setImmediate();
-          case 18:
+          case 20:
             throw new DstoreError('datastore.update error', _context6.t1);
-          case 19:
-            _context6.prev = 19;
+          case 21:
+            _context6.prev = 21;
             metricEnd({
               operation: 'update'
             });
-            return _context6.finish(19);
-          case 22:
+            return _context6.finish(21);
+          case 24:
             return _context6.abrupt("return", ret);
-          case 23:
+          case 25:
           case "end":
             return _context6.stop();
         }
-      }, _callee6, this, [[4, 13, 19, 22]]);
+      }, _callee6, this, [[4, 15, 21, 24]]);
     }));
     function update(_x7) {
       return _update.apply(this, arguments);
@@ -1283,7 +1328,7 @@ var Dstore = /*#__PURE__*/function () {
   /*#__PURE__*/
   function () {
     var _query = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regeneratorRuntime().mark(function _callee9(kindName, filters, limit, ordering, selection, cursor) {
-      var q, _iterator4, _step4, filterSpec, _iterator5, _step5, orderField;
+      var q, _iterator4, _step4, filterSpec, _iterator5, _step5, orderField, ret;
       return _regeneratorRuntime().wrap(function _callee9$(_context9) {
         while (1) switch (_context9.prev = _context9.next) {
           case 0:
@@ -1321,26 +1366,27 @@ var Dstore = /*#__PURE__*/function () {
               q.select(selection);
             }
             _context9.next = 15;
-            return this.runQuery(q);
+            return this.getDoT().runQuery(q);
           case 15:
-            return _context9.abrupt("return", _context9.sent);
-          case 18:
-            _context9.prev = 18;
+            ret = _context9.sent;
+            return _context9.abrupt("return", [this.fixKeys(ret[0]), ret[1]]);
+          case 19:
+            _context9.prev = 19;
             _context9.t0 = _context9["catch"](7);
-            _context9.next = 22;
+            _context9.next = 23;
             return promises.setImmediate();
-          case 22:
+          case 23:
             throw new DstoreError('datastore.query error', _context9.t0, {
               kindName: kindName,
               filters: filters,
               limit: limit,
               ordering: ordering
             });
-          case 23:
+          case 24:
           case "end":
             return _context9.stop();
         }
-      }, _callee9, this, [[7, 18]]);
+      }, _callee9, this, [[7, 19]]);
     }));
     function query(_x10, _x11, _x12, _x13, _x14, _x15) {
       return _query.apply(this, arguments);
@@ -1352,12 +1398,21 @@ var Dstore = /*#__PURE__*/function () {
    * It takes a Parameter object and returns an AsyncIterable.
    * Entities returned have been processed by `fixKeys()`.
    *
+   * Can be used with `for await` loops like this:
+   *
+   * ```typescript
+   * for await (const entity of dstore.iterate({ kindName: 'p_ReservierungsAbruf', filters: [['verbucht', '=', true]]})) {
+   *   console.log(entity)
+   * }
+   * ```
+   *
    * @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
    */
   ;
@@ -1401,72 +1456,73 @@ var Dstore = /*#__PURE__*/function () {
             _iteratorAbruptCompletion = false;
             _didIteratorError = false;
             _context10.prev = 11;
-            _iterator = _asyncIterator(_this.getDoT().runStream(q));
+            _iterator = _asyncIterator(q.runStream());
           case 13:
             _context10.next = 15;
             return _awaitAsyncGenerator(_iterator.next());
           case 15:
             if (!(_iteratorAbruptCompletion = !(_step = _context10.sent).done)) {
-              _context10.next = 24;
+              _context10.next = 25;
               break;
             }
             _entity = _step.value;
             ret = _this.fixKeys([_entity])[0];
             assertateDebug.assertIsDefined(ret, 'datastore.iterate: entity is undefined');
-            _context10.next = 21;
+            assertIsKey(ret[datastore.Datastore.KEY]);
+            _context10.next = 22;
             return ret;
-          case 21:
+          case 22:
             _iteratorAbruptCompletion = false;
             _context10.next = 13;
             break;
-          case 24:
-            _context10.next = 30;
+          case 25:
+            _context10.next = 31;
             break;
-          case 26:
-            _context10.prev = 26;
+          case 27:
+            _context10.prev = 27;
             _context10.t0 = _context10["catch"](11);
             _didIteratorError = true;
             _iteratorError = _context10.t0;
-          case 30:
-            _context10.prev = 30;
+          case 31:
             _context10.prev = 31;
+            _context10.prev = 32;
             if (!(_iteratorAbruptCompletion && _iterator["return"] != null)) {
-              _context10.next = 35;
+              _context10.next = 36;
               break;
             }
-            _context10.next = 35;
+            _context10.next = 36;
             return _awaitAsyncGenerator(_iterator["return"]());
-          case 35:
-            _context10.prev = 35;
+          case 36:
+            _context10.prev = 36;
             if (!_didIteratorError) {
-              _context10.next = 38;
+              _context10.next = 39;
               break;
             }
             throw _iteratorError;
-          case 38:
-            return _context10.finish(35);
           case 39:
-            return _context10.finish(30);
+            return _context10.finish(36);
           case 40:
-            _context10.next = 47;
+            return _context10.finish(31);
+          case 41:
+            _context10.next = 48;
             break;
-          case 42:
-            _context10.prev = 42;
+          case 43:
+            _context10.prev = 43;
             _context10.t1 = _context10["catch"](3);
-            _context10.next = 46;
+            _context10.next = 47;
             return _awaitAsyncGenerator(promises.setImmediate());
-          case 46:
+          case 47:
             throw new DstoreError('datastore.query error', _context10.t1, {
               kindName: kindName,
               filters: filters,
               limit: limit,
               ordering: ordering
             });
-          case 47:
+          case 48:
           case "end":
             return _context10.stop();
         }
-      }, _callee10, null, [[3, 42], [11, 26, 30, 40], [31,, 35, 39]]);
+      }, _callee10, null, [[3, 43], [11, 27, 31, 41], [32,, 36, 40]]);
     }))();
   }
   /** Allocate one ID in the Datastore.
@@ -1620,35 +1676,6 @@ var DstoreError = /*#__PURE__*/function (_Error) {
   return DstoreError;
 }(/*#__PURE__*/_wrapNativeSuper(Error));
 
-/*
- * assert.ts
- *
- * Created by Dr. Maximillian Dornseif 2025-04-11 in datastore-api 6.0.1
- */
-/**
- * Generates an type assertion message for the given `value`
- *
- * @param value value being type-checked
- * @param type the expected value as a string; eg 'string', 'boolean', 'number'
- * @param variableName the name of the variable being type-checked
- * @param additionalMessage further information on failure
- */
-var AssertionMessage = function AssertionMessage(value, type, variableName, additionalMessage) {
-  var message = variableName ? variableName + " must be of type '" + type + "', '" + assertateDebug.getType(value) + "' provided" : "expected value of type '" + type + "', '" + assertateDebug.getType(value) + "' provided";
-  return additionalMessage ? message + ": " + additionalMessage : message;
-};
-/**
- * Type-checks the provided `value` to be a symbol, throws an Error if it is not
- *
- * @param value the value to type-check as a symbol
- * @param variableName the name of the variable to be type-checked
- * @param additionalMessage further information on failure
- * @throws {Error}
- */
-function assertIsKey(value, variableName, additionalMessage) {
-  assertateDebug.assert(datastore.Datastore.isKey(value), AssertionMessage(value, "Key", variableName, additionalMessage));
-}
-
 Object.defineProperty(exports, 'Datastore', {
   enumerable: true,
   get: function () { return datastore.Datastore; }