spice-js 2.7.30 → 2.7.32

package/build/models/SpiceModel.js

@@ -7,9 +7,9 @@ var _ResourceLifecycleTriggered = _interopRequireDefault(require("../events/even
 var _Security = require("../utility/Security");
 var _fix = require("../utility/fix");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) { ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } } return n; }, _extends.apply(null, arguments); }
 function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
 function _asyncToGenerator(n) { return function () { var t = this, e = arguments; return new Promise(function (r, o) { var a = n.apply(t, e); function _next(n) { asyncGeneratorStep(a, r, o, _next, _throw, "next", n); } function _throw(n) { asyncGeneratorStep(a, r, o, _next, _throw, "throw", n); } _next(void 0); }); }; }
-function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) { ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } } return n; }, _extends.apply(null, arguments); }
 var co = require("co");
 var regeneratorRuntime = require("regenerator-runtime");
 var SDate = require("sonover-date"),
@@ -29,11 +29,74 @@ var SDate = require("sonover-date"),
   _mapping_dept = Symbol(),
   _mapping_dept_scalar = Symbol(),
   _mapping_dept_array = Symbol(),
+  _mapping_concurrency = Symbol(),
+  _skip_mapped_serialization = Symbol(),
   _mapping_dept_exempt = Symbol(),
   _current_path = Symbol();
-
-//const _type = Symbol("type");
-
+var GLOBAL_MAPPING_CONCURRENCY = Math.max(1, Number(process.env.SPICE_MAPPING_GLOBAL_CONCURRENCY) || 32);
+var activeGlobalMappings = 0;
+var globalMappingWaiters = [];
+function normalizeConcurrency(value, fallback) {
+  if (fallback === void 0) {
+    fallback = 1;
+  }
+  var parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function acquireGlobalMappingSlot() {
+  return _acquireGlobalMappingSlot.apply(this, arguments);
+}
+function _acquireGlobalMappingSlot() {
+  _acquireGlobalMappingSlot = _asyncToGenerator(function* () {
+    var queuedAt = process.hrtime.bigint();
+    if (activeGlobalMappings < GLOBAL_MAPPING_CONCURRENCY) {
+      activeGlobalMappings += 1;
+    } else {
+      yield new Promise(resolve => globalMappingWaiters.push(resolve));
+    }
+    return {
+      active: activeGlobalMappings,
+      waitMs: Number(process.hrtime.bigint() - queuedAt) / 1e6,
+      release() {
+        var next = globalMappingWaiters.shift();
+        if (next) {
+          next();
+        } else {
+          activeGlobalMappings -= 1;
+        }
+      }
+    };
+  });
+  return _acquireGlobalMappingSlot.apply(this, arguments);
+}
+function runWithConcurrency(_x, _x2, _x3) {
+  return _runWithConcurrency.apply(this, arguments);
+} //const _type = Symbol("type");
+function _runWithConcurrency() {
+  _runWithConcurrency = _asyncToGenerator(function* (items, concurrency, worker) {
+    var results = new Array(items.length);
+    var nextIndex = 0;
+    function runWorker() {
+      return _runWorker.apply(this, arguments);
+    }
+    function _runWorker() {
+      _runWorker = _asyncToGenerator(function* () {
+        while (nextIndex < items.length) {
+          var index = nextIndex;
+          nextIndex += 1;
+          results[index] = yield worker(items[index], index);
+        }
+      });
+      return _runWorker.apply(this, arguments);
+    }
+    var workerCount = Math.min(concurrency, items.length);
+    yield Promise.all(Array.from({
+      length: workerCount
+    }, () => runWorker()));
+    return results;
+  });
+  return _runWithConcurrency.apply(this, arguments);
+}
 var that;
 if (!Promise.allSettled) {
   Promise.allSettled = promises => Promise.all(promises.map((promise, i) => promise.then(value => ({
@@ -50,7 +113,7 @@ class SpiceModel {
       args = {};
     }
     try {
-      var _args2, _modelArgs$ctx, _modelArgs$ctx$state, _ref, _ref2, _modelArgs$mapping_de, _ref3, _ref4, _modelArgs$mapping_de2, _args$args, _args3, _args3$args, _args4, _args4$args, _args5, _args5$args, _args6, _args6$args, _args7, _args7$args;
+      var _args2, _modelArgs$ctx, _modelArgs$ctx$state, _ref, _ref2, _modelArgs$mapping_de, _ref3, _ref4, _modelArgs$mapping_de2, _modelArgs$mapping_co, _ref5, _modelArgs$skip_mappe, _args$args, _args3, _args3$args, _args4, _args4$args, _args5, _args5$args, _args6, _args6$args, _args7, _args7$args;
       var modelArgs = ((_args2 = args) == null ? void 0 : _args2.args) || {};
       var requestProfile = (modelArgs == null ? void 0 : (_modelArgs$ctx = modelArgs.ctx) == null ? void 0 : (_modelArgs$ctx$state = _modelArgs$ctx.state) == null ? void 0 : _modelArgs$ctx$state.read_profile) || {};
       var defaultMappingDept = process.env.MAPPING_DEPT || 3;
@@ -60,6 +123,8 @@ class SpiceModel {
       this[_mapping_dept] = legacyMappingDept != null ? legacyMappingDept : defaultMappingDept;
       this[_mapping_dept_scalar] = (_ref = (_ref2 = (_modelArgs$mapping_de = modelArgs.mapping_dept_scalar) != null ? _modelArgs$mapping_de : legacyMappingDept) != null ? _ref2 : requestProfile.mapping_dept_scalar) != null ? _ref : defaultMappingDept;
       this[_mapping_dept_array] = (_ref3 = (_ref4 = (_modelArgs$mapping_de2 = modelArgs.mapping_dept_array) != null ? _modelArgs$mapping_de2 : legacyMappingDept) != null ? _ref4 : requestProfile.mapping_dept_array) != null ? _ref3 : defaultMappingDept;
+      this[_mapping_concurrency] = normalizeConcurrency((_modelArgs$mapping_co = modelArgs.mapping_concurrency) != null ? _modelArgs$mapping_co : requestProfile.mapping_concurrency);
+      this[_skip_mapped_serialization] = (_ref5 = (_modelArgs$skip_mappe = modelArgs.skip_mapped_serialization) != null ? _modelArgs$skip_mappe : requestProfile.skip_mapped_serialization) != null ? _ref5 : false;
       this[_mapping_dept_exempt] = modelArgs.mapping_dept_exempt || [];
       this.type = "";
       this.collection = args.connection;
@@ -233,6 +298,12 @@ class SpiceModel {
     if (args.mapping_dept_array !== undefined && args.mapping_dept_array !== null) {
       this[_mapping_dept_array] = args.mapping_dept_array;
     }
+    if (args.skip_mapped_serialization !== undefined) {
+      this[_skip_mapped_serialization] = args.skip_mapped_serialization;
+    }
+    if (args.mapping_concurrency !== undefined) {
+      this[_mapping_concurrency] = normalizeConcurrency(args.mapping_concurrency, this[_mapping_concurrency]);
+    }
     if (args.mapping_dept_exempt) {
       this[_mapping_dept_exempt] = args.mapping_dept_exempt;
     }
@@ -278,13 +349,13 @@ class SpiceModel {
       return [];
     })();
   }
-  createValidationString(_ref5) {
+  createValidationString(_ref6) {
     var {
       property_name,
       props,
       operation,
       complete
-    } = _ref5;
+    } = _ref6;
     var operationExempt = {
       PUT: ["required", "unique"]
     };
@@ -515,7 +586,7 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this4$_ctx = _this4[_ctx]) == null ? void 0 : _this4$_ctx.profiler;
       var doGet = /*#__PURE__*/function () {
-        var _ref6 = _asyncToGenerator(function* () {
+        var _ref7 = _asyncToGenerator(function* () {
           if (!args) {
             args = {};
           }
@@ -624,7 +695,7 @@ class SpiceModel {
           }
         });
         return function doGet() {
-          return _ref6.apply(this, arguments);
+          return _ref7.apply(this, arguments);
         };
       }();
       try {
@@ -641,17 +712,44 @@ class SpiceModel {
       }
     })();
   }
-  query(query, scope) {
+  query(query, scope, options) {
     var _this5 = this;
     return _asyncToGenerator(function* () {
       try {
-        var results = yield _this5.database.query(query, scope);
+        var results = yield _this5.database.query(query, scope, options);
         return results;
       } catch (error) {
         throw error;
       }
     })();
   }
+  getQueryOptions(args) {
+    if (args === void 0) {
+      args = {};
+    }
+    var scanConsistency = args.scan_consistency;
+
+    // Backward compatibility for callers that already use statement_consistent.
+    // The adapter accepts the SDK-style value as well as these snake_case keys.
+    if (scanConsistency === undefined && args.statement_consistent !== undefined) {
+      var legacyValue = args.statement_consistent;
+      var isRequestPlus = legacyValue === true || typeof legacyValue === "string" && ["true", "request_plus"].includes(legacyValue.toLowerCase());
+      scanConsistency = isRequestPlus ? "request_plus" : "not_bounded";
+    }
+    return {
+      scan_consistency: scanConsistency,
+      consistent_with: args.consistent_with,
+      scan_wait: args.scan_wait
+    };
+  }
+  requiresFreshQuery(args) {
+    if (args === void 0) {
+      args = {};
+    }
+    var options = this.getQueryOptions(args);
+    var scanConsistency = options.scan_consistency;
+    return options.consistent_with !== undefined || scanConsistency === true || typeof scanConsistency === "string" && ["true", "request_plus"].includes(scanConsistency.toLowerCase());
+  }
   getMulti(args) {
     var _this6 = this;
     return _asyncToGenerator(function* () {
@@ -659,7 +757,7 @@ class SpiceModel {
       // ⚡ Profiling: use track() for proper async context forking
       var p = (_this6$_ctx = _this6[_ctx]) == null ? void 0 : _this6$_ctx.profiler;
       var doGetMulti = /*#__PURE__*/function () {
-        var _ref9 = _asyncToGenerator(function* () {
+        var _ref0 = _asyncToGenerator(function* () {
           if (!args) {
             args = {};
           }
@@ -701,7 +799,7 @@ class SpiceModel {
           return results;
         });
         return function doGetMulti() {
-          return _ref9.apply(this, arguments);
+          return _ref0.apply(this, arguments);
         };
       }();
       try {
@@ -757,7 +855,7 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this8$_ctx = _this8[_ctx]) == null ? void 0 : _this8$_ctx.profiler;
       var doUpdate = /*#__PURE__*/function () {
-        var _ref0 = _asyncToGenerator(function* () {
+        var _ref1 = _asyncToGenerator(function* () {
           _this8.updated_at = new SDate().now();
           var results = yield _this8.database.get(args.id);
           var item_exist = yield _this8.exist(results);
@@ -801,7 +899,7 @@ class SpiceModel {
           });
         });
         return function doUpdate() {
-          return _ref0.apply(this, arguments);
+          return _ref1.apply(this, arguments);
         };
       }();
       try {
@@ -827,7 +925,7 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this9$_ctx = _this9[_ctx]) == null ? void 0 : _this9$_ctx.profiler;
       var doCreate = /*#__PURE__*/function () {
-        var _ref10 = _asyncToGenerator(function* () {
+        var _ref11 = _asyncToGenerator(function* () {
           var form;
           _this9.created_at = new SDate().now();
           args = _.defaults(args, {
@@ -873,7 +971,7 @@ class SpiceModel {
           });
         });
         return function doCreate() {
-          return _ref10.apply(this, arguments);
+          return _ref11.apply(this, arguments);
         };
       }();
       try {
@@ -911,7 +1009,7 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this1$_ctx = _this1[_ctx]) == null ? void 0 : _this1$_ctx.profiler;
       var doDelete = /*#__PURE__*/function () {
-        var _ref12 = _asyncToGenerator(function* () {
+        var _ref13 = _asyncToGenerator(function* () {
           var item_exist = yield _this1.exist(args.id);
           if (!item_exist) {
             throw new Error(_this1.type + " does not exist.");
@@ -922,7 +1020,7 @@ class SpiceModel {
           }
           var delete_response = {};
           var dbOperation = /*#__PURE__*/function () {
-            var _ref13 = _asyncToGenerator(function* () {
+            var _ref14 = _asyncToGenerator(function* () {
               if (args.hard) {
                 delete_response = yield _this1.database.delete(args.id);
                 _this1.setMonitor();
@@ -933,7 +1031,7 @@ class SpiceModel {
               }
             });
             return function dbOperation() {
-              return _ref13.apply(this, arguments);
+              return _ref14.apply(this, arguments);
             };
           }();
           if (p) {
@@ -949,7 +1047,7 @@ class SpiceModel {
           return {};
         });
         return function doDelete() {
-          return _ref12.apply(this, arguments);
+          return _ref13.apply(this, arguments);
         };
       }();
       try {
@@ -1139,12 +1237,12 @@ class SpiceModel {
   }
   createJoinSection(mappedNestings) {
     if (!mappedNestings || mappedNestings.length === 0) return "";
-    return mappedNestings.map(_ref14 => {
+    return mappedNestings.map(_ref15 => {
       var {
         alias,
         reference,
         is_array
-      } = _ref14;
+      } = _ref15;
       var keyspace = (0, _fix.fixCollection)(reference);
       if (is_array === true) {
         return "LEFT NEST `" + keyspace + "` AS `" + alias + "` ON KEYS `" + this.type + "`.`" + alias + "`";
@@ -1289,7 +1387,7 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this10$_ctx = _this10[_ctx]) == null ? void 0 : _this10$_ctx.profiler;
       var doList = /*#__PURE__*/function () {
-        var _ref15 = _asyncToGenerator(function* () {
+        var _ref16 = _asyncToGenerator(function* () {
           var _args1, _args10;
           _this10.applyMappingDepthArgs(args);
 
@@ -1338,9 +1436,9 @@ class SpiceModel {
           if (args.skip_hooks !== true) {
             yield _this10.run_hook(_this10, "list", "before");
           }
-          var cacheKey = "list::" + _this10.type + "::" + args._join + "::" + query + "::" + args.limit + "::" + args.offset + "::" + args.sort + "::" + args.do_count + "::" + args.statement_consistent + "::" + args.columns + "::" + args.is_full_text + "::" + args.is_custom_query;
+          var cacheKey = "list::" + _this10.type + "::" + args._join + "::" + query + "::" + args.limit + "::" + args.offset + "::" + args.sort + "::" + args.do_count + "::" + args.query_scope + "::" + args.scan_consistency + "::" + args.statement_consistent + "::" + args.scan_wait + "::" + args.columns + "::" + args.is_full_text + "::" + args.is_custom_query;
           var results;
-          if (_this10.shouldUseCache(_this10.type)) {
+          if (_this10.shouldUseCache(_this10.type) && !_this10.requiresFreshQuery(args)) {
             var cached = yield _this10.getCacheProviderObject(_this10.type).get(cacheKey);
             results = cached == null ? void 0 : cached.value;
             var isEmpty = (cached == null ? void 0 : cached.value) === undefined;
@@ -1368,7 +1466,7 @@ class SpiceModel {
           return results;
         });
         return function doList() {
-          return _ref15.apply(this, arguments);
+          return _ref16.apply(this, arguments);
         };
       }();
       try {
@@ -1422,20 +1520,21 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this11$_ctx = _this11[_ctx]) == null ? void 0 : _this11$_ctx.profiler;
       var doFetch = /*#__PURE__*/function () {
-        var _ref16 = _asyncToGenerator(function* () {
+        var _ref17 = _asyncToGenerator(function* () {
+          var queryOptions = _this11.getQueryOptions(args);
           if (args.is_custom_query === "true" && args.ids.length > 0) {
             console.log("Fetching results from database", _this11.type, args, query, mappedNestings);
-            return yield _this11.database.query(query);
+            return yield _this11.database.query(query, args.query_scope, queryOptions);
           } else if (args.is_full_text === "true") {
             return yield _this11.database.full_text_search(_this11.type, query || "", args.limit, args.offset, args._join);
           } else {
             var correctedColumns = _this11.correctColumns(args.columns, mappedNestings);
-            var result = yield _this11.database.search(_this11.type, correctedColumns || args.columns || "", query || "", args.limit, args.offset, args.sort, args.do_count, args.statement_consistent, args._join);
+            var result = yield _this11.database.search(_this11.type, correctedColumns || args.columns || "", query || "", args.limit, args.offset, args.sort, args.do_count, args.query_scope, args._join, queryOptions);
             return result;
           }
         });
         return function doFetch() {
-          return _ref16.apply(this, arguments);
+          return _ref17.apply(this, arguments);
         };
       }();
       if (p) {
@@ -1444,12 +1543,12 @@ class SpiceModel {
       return yield doFetch();
     })();
   }
-  addHook(_ref17) {
+  addHook(_ref18) {
     var {
       operation,
       when,
       execute
-    } = _ref17;
+    } = _ref18;
     this[_hooks][operation][when].push(execute);
   }
   run_hook(data, op, when, old_data) {
@@ -1572,7 +1671,7 @@ class SpiceModel {
 
         // ⚡ Wrap in profiler track() to ensure proper async context for child operations
         var fetchRelated = /*#__PURE__*/function () {
-          var _ref18 = _asyncToGenerator(function* () {
+          var _ref19 = _asyncToGenerator(function* () {
             return yield Promise.allSettled(_.map(classes, obj => {
               var objInstance = new obj(_extends({}, _this13[_args], {
                 skip_cache: _this13[_skip_cache],
@@ -1580,6 +1679,8 @@ class SpiceModel {
                 mapping_dept: _this13[_mapping_dept],
                 mapping_dept_scalar: _this13[_mapping_dept_scalar],
                 mapping_dept_array: _this13[_mapping_dept_array],
+                mapping_concurrency: _this13[_mapping_concurrency],
+                skip_mapped_serialization: _this13[_skip_mapped_serialization],
                 mapping_dept_exempt: _this13[_mapping_dept_exempt],
                 _columns: columnArray.join(","),
                 _current_path: childPath
@@ -1587,12 +1688,13 @@ class SpiceModel {
               return objInstance.getMulti({
                 skip_hooks: true,
                 ids: ids,
-                columns: columnArray
+                columns: columnArray,
+                skip_read_serialize: _this13[_skip_mapped_serialization]
               });
             }));
           });
           return function fetchRelated() {
-            return _ref18.apply(this, arguments);
+            return _ref19.apply(this, arguments);
           };
         }();
         var returned_all;
@@ -1693,7 +1795,7 @@ class SpiceModel {
 
         // ⚡ Wrap in profiler track() to ensure proper async context for child operations
         var fetchRelated = /*#__PURE__*/function () {
-          var _ref19 = _asyncToGenerator(function* () {
+          var _ref20 = _asyncToGenerator(function* () {
             return yield Promise.allSettled(_.map(classes, obj => {
               return new obj(_extends({}, _this14[_args], {
                 skip_cache: _this14[_skip_cache],
@@ -1701,18 +1803,21 @@ class SpiceModel {
                 mapping_dept: _this14[_mapping_dept],
                 mapping_dept_scalar: _this14[_mapping_dept_scalar],
                 mapping_dept_array: _this14[_mapping_dept_array],
+                mapping_concurrency: _this14[_mapping_concurrency],
+                skip_mapped_serialization: _this14[_skip_mapped_serialization],
                 mapping_dept_exempt: _this14[_mapping_dept_exempt],
                 _columns: columnArray.join(","),
                 _current_path: childPath
               })).getMulti({
                 skip_hooks: true,
                 ids: ids,
-                columns: columnArray
+                columns: columnArray,
+                skip_read_serialize: _this14[_skip_mapped_serialization]
               });
             }));
           });
           return function fetchRelated() {
-            return _ref19.apply(this, arguments);
+            return _ref20.apply(this, arguments);
           };
         }();
         var returned_all;
@@ -1760,12 +1865,22 @@ class SpiceModel {
       return original_is_array ? data : data[0];
     })();
   }
-  addModifier(_ref20) {
+  addModifier(_ref21) {
     var {
       when,
-      execute
-    } = _ref20;
+      execute,
+      kind,
+      source_property,
+      store_property
+    } = _ref21;
     if (this[_serializers][when]) {
+      if (kind) {
+        execute.spiceModifier = {
+          kind,
+          source_property,
+          store_property
+        };
+      }
       this[_serializers][when]["modifiers"].push(execute);
     }
   }
@@ -1833,6 +1948,9 @@ class SpiceModel {
                   {
                     _this15.addModifier({
                       when: properties[i].map.when || "read",
+                      kind: "relationship_map",
+                      source_property: i,
+                      store_property: properties[i].map.destination || i,
                       execute: function () {
                         var _execute = _asyncToGenerator(function* (data, old_data, ctx, type, args, mapping_dept, level, columns, serializationType) {
                           // Skip if columns are specified but this field isn't included
@@ -1841,7 +1959,7 @@ class SpiceModel {
                           }
                           return yield _this15.mapToObject(data, _.isString(properties[i].map.reference) ? spice.models[properties[i].map.reference] : properties[i].map.reference, i, properties[i].map.destination || i, properties[i], args, serializationType, mapping_dept, level, columns);
                         });
-                        function execute(_x, _x2, _x3, _x4, _x5, _x6, _x7, _x8, _x9) {
+                        function execute(_x4, _x5, _x6, _x7, _x8, _x9, _x0, _x1, _x10) {
                           return _execute.apply(this, arguments);
                         }
                         return execute;
@@ -1854,6 +1972,9 @@ class SpiceModel {
                   {
                     _this15.addModifier({
                       when: properties[i].map.when || "read",
+                      kind: "relationship_map",
+                      source_property: i,
+                      store_property: properties[i].map.destination || i,
                       execute: function () {
                         var _execute2 = _asyncToGenerator(function* (data, old_data, ctx, type, args, mapping_dept, level, columns, serializationType) {
                           // Skip if columns are specified but this field isn't included
@@ -1862,7 +1983,7 @@ class SpiceModel {
                           }
                           return yield _this15.mapToObjectArray(data, _.isString(properties[i].map.reference) ? spice.models[properties[i].map.reference] : properties[i].map.reference, i, properties[i].map.destination || i, properties[i], args, serializationType, mapping_dept, level, columns);
                         });
-                        function execute(_x0, _x1, _x10, _x11, _x12, _x13, _x14, _x15, _x16) {
+                        function execute(_x11, _x12, _x13, _x14, _x15, _x16, _x17, _x18, _x19) {
                           return _execute2.apply(this, arguments);
                         }
                         return execute;
@@ -1894,7 +2015,7 @@ class SpiceModel {
       // Profiling: use track() for proper async context forking
       var p = (_this16$_ctx = _this16[_ctx]) == null ? void 0 : _this16$_ctx.profiler;
       var doSerialize = /*#__PURE__*/function () {
-        var _ref21 = _asyncToGenerator(function* () {
+        var _ref22 = _asyncToGenerator(function* () {
           var _this16$_serializers, _this16$_serializers$;
           // Early exit if serialization should not run.
           if (!_this16.shouldSerializerRun(args, type)) {
@@ -1909,19 +2030,117 @@ class SpiceModel {
 
           // Cache the modifiers lookup for the specified type.
           var modifiers = ((_this16$_serializers = _this16[_serializers]) == null ? void 0 : (_this16$_serializers$ = _this16$_serializers[type]) == null ? void 0 : _this16$_serializers$.modifiers) || [];
-          for (var i = 0; i < modifiers.length; i++) {
-            var modifier = modifiers[i];
-            try {
-              var result = yield modifier(data, old_data, _this16[_ctx], _this16.type, args, _this16[_mapping_dept], _this16[_level], _this16[_columns], type);
-              // Guard against modifiers that return undefined
-              if (result !== undefined) {
-                data = result;
-              } else {
-                console.warn("Modifier #" + i + " for type=" + _this16.type + " returned undefined, keeping previous data");
+          var invokeModifier = /*#__PURE__*/function () {
+            var _ref23 = _asyncToGenerator(function* (modifier, index, inputData) {
+              try {
+                var result = yield modifier(inputData, old_data, _this16[_ctx], _this16.type, args, _this16[_mapping_dept], _this16[_level], _this16[_columns], type);
+                if (result !== undefined) {
+                  return {
+                    hasValue: true,
+                    value: result
+                  };
+                }
+                console.warn("Modifier #" + index + " for type=" + _this16.type + " returned undefined, keeping previous data");
+              } catch (error) {
+                console.error("Modifier error in do_serialize (type=" + _this16.type + ", modifier #" + index + "):", error instanceof Error ? error.stack : "Non-Error thrown: " + JSON.stringify(error));
               }
-            } catch (error) {
-              console.error("Modifier error in do_serialize (type=" + _this16.type + ", modifier #" + i + "):", error instanceof Error ? error.stack : "Non-Error thrown: " + JSON.stringify(error));
+              return {
+                hasValue: false
+              };
+            });
+            return function invokeModifier(_x20, _x21, _x22) {
+              return _ref23.apply(this, arguments);
+            };
+          }();
+          var modifierIndex = 0;
+          var _loop2 = function* _loop2() {
+            var _modifier$spiceModifi;
+            var modifier = modifiers[modifierIndex];
+            var canRunRelationshipMapsConcurrently = type === "read" && _this16[_level] === 0 && _this16[_mapping_concurrency] > 1 && (modifier == null ? void 0 : (_modifier$spiceModifi = modifier.spiceModifier) == null ? void 0 : _modifier$spiceModifi.kind) === "relationship_map";
+            if (!canRunRelationshipMapsConcurrently) {
+              var result = yield invokeModifier(modifier, modifierIndex, data);
+              if (result.hasValue) data = result.value;
+              modifierIndex += 1;
+              return "continue";
             }
+            var group = [];
+            var destinations = new Set();
+            while (modifierIndex < modifiers.length) {
+              var candidate = modifiers[modifierIndex];
+              var metadata = candidate == null ? void 0 : candidate.spiceModifier;
+              if ((metadata == null ? void 0 : metadata.kind) !== "relationship_map") break;
+              if (metadata.store_property && destinations.has(metadata.store_property)) {
+                break;
+              }
+              if (metadata.store_property) {
+                destinations.add(metadata.store_property);
+              }
+              group.push({
+                modifier: candidate,
+                index: modifierIndex,
+                metadata
+              });
+              modifierIndex += 1;
+            }
+            var groupQueuedAt = process.hrtime.bigint();
+            var activeRequestMappings = 0;
+            var executeGroup = /*#__PURE__*/function () {
+              var _ref24 = _asyncToGenerator(function* () {
+                return yield runWithConcurrency(group, _this16[_mapping_concurrency], /*#__PURE__*/function () {
+                  var _ref25 = _asyncToGenerator(function* (entry) {
+                    var requestQueueWaitMs = Number(process.hrtime.bigint() - groupQueuedAt) / 1e6;
+                    var globalSlot = yield acquireGlobalMappingSlot();
+                    activeRequestMappings += 1;
+                    var profileMetadata = {
+                      source_property: entry.metadata.source_property,
+                      store_property: entry.metadata.store_property,
+                      request_queue_wait_ms: Math.round(requestQueueWaitMs * 100) / 100,
+                      global_queue_wait_ms: Math.round(globalSlot.waitMs * 100) / 100,
+                      active_request_mappings: activeRequestMappings,
+                      request_limit: _this16[_mapping_concurrency],
+                      active_global_mappings: globalSlot.active,
+                      global_limit: GLOBAL_MAPPING_CONCURRENCY
+                    };
+                    try {
+                      var execute = /*#__PURE__*/function () {
+                        var _ref26 = _asyncToGenerator(function* () {
+                          return yield invokeModifier(entry.modifier, entry.index, data);
+                        });
+                        return function execute() {
+                          return _ref26.apply(this, arguments);
+                        };
+                      }();
+                      if (p) {
+                        return yield p.track(_this16.type + ".map.concurrent." + entry.metadata.source_property, execute, profileMetadata);
+                      }
+                      return yield execute();
+                    } finally {
+                      activeRequestMappings -= 1;
+                      globalSlot.release();
+                    }
+                  });
+                  return function (_x23) {
+                    return _ref25.apply(this, arguments);
+                  };
+                }());
+              });
+              return function executeGroup() {
+                return _ref24.apply(this, arguments);
+              };
+            }();
+            var groupMetadata = {
+              map_count: group.length,
+              request_limit: _this16[_mapping_concurrency],
+              global_limit: GLOBAL_MAPPING_CONCURRENCY
+            };
+            var groupResults = p ? yield p.track(_this16.type + ".map.concurrent", executeGroup, groupMetadata) : yield executeGroup();
+            for (var _result of groupResults) {
+              if (_result == null ? void 0 : _result.hasValue) data = _result.value;
+            }
+          };
+          while (modifierIndex < modifiers.length) {
+            var _ret = yield* _loop2();
+            if (_ret === "continue") continue;
           }
 
           // Ensure data is always an array for consistent processing.
@@ -1962,7 +2181,7 @@ class SpiceModel {
           return originalIsArray ? data : data[0];
         });
         return function doSerialize() {
-          return _ref21.apply(this, arguments);
+          return _ref22.apply(this, arguments);
         };
       }();
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spice-js",
-  "version": "2.7.30",
+  "version": "2.7.32",
   "description": "spice",
   "main": "build/index.js",
   "repository": {

package/src/models/SpiceModel.js

@@ -24,9 +24,64 @@ var SDate = require("sonover-date"),
   _mapping_dept = Symbol(),
   _mapping_dept_scalar = Symbol(),
   _mapping_dept_array = Symbol(),
+  _mapping_concurrency = Symbol(),
+  _skip_mapped_serialization = Symbol(),
   _mapping_dept_exempt = Symbol(),
   _current_path = Symbol();
 
+const GLOBAL_MAPPING_CONCURRENCY = Math.max(
+  1,
+  Number(process.env.SPICE_MAPPING_GLOBAL_CONCURRENCY) || 32,
+);
+let activeGlobalMappings = 0;
+const globalMappingWaiters = [];
+
+function normalizeConcurrency(value, fallback = 1) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+async function acquireGlobalMappingSlot() {
+  const queuedAt = process.hrtime.bigint();
+  if (activeGlobalMappings < GLOBAL_MAPPING_CONCURRENCY) {
+    activeGlobalMappings += 1;
+  } else {
+    await new Promise((resolve) => globalMappingWaiters.push(resolve));
+  }
+
+  return {
+    active: activeGlobalMappings,
+    waitMs: Number(process.hrtime.bigint() - queuedAt) / 1e6,
+    release() {
+      const next = globalMappingWaiters.shift();
+      if (next) {
+        next();
+      } else {
+        activeGlobalMappings -= 1;
+      }
+    },
+  };
+}
+
+async function runWithConcurrency(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  async function runWorker() {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await worker(items[index], index);
+    }
+  }
+
+  const workerCount = Math.min(concurrency, items.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, () => runWorker()),
+  );
+  return results;
+}
+
 //const _type = Symbol("type");
 
 let that;
@@ -71,6 +126,13 @@ export default class SpiceModel {
         legacyMappingDept ??
         requestProfile.mapping_dept_array ??
         defaultMappingDept;
+      this[_mapping_concurrency] = normalizeConcurrency(
+        modelArgs.mapping_concurrency ?? requestProfile.mapping_concurrency,
+      );
+      this[_skip_mapped_serialization] =
+        modelArgs.skip_mapped_serialization ??
+        requestProfile.skip_mapped_serialization ??
+        false;
       this[_mapping_dept_exempt] = modelArgs.mapping_dept_exempt || [];
       this.type = "";
       this.collection = args.connection;
@@ -277,6 +339,15 @@ export default class SpiceModel {
     ) {
       this[_mapping_dept_array] = args.mapping_dept_array;
     }
+    if (args.skip_mapped_serialization !== undefined) {
+      this[_skip_mapped_serialization] = args.skip_mapped_serialization;
+    }
+    if (args.mapping_concurrency !== undefined) {
+      this[_mapping_concurrency] = normalizeConcurrency(
+        args.mapping_concurrency,
+        this[_mapping_concurrency],
+      );
+    }
     if (args.mapping_dept_exempt) {
       this[_mapping_dept_exempt] = args.mapping_dept_exempt;
     }
@@ -712,15 +783,47 @@ export default class SpiceModel {
     }
   }
 
-  async query(query, scope) {
+  async query(query, scope, options) {
     try {
-      let results = await this.database.query(query, scope);
+      let results = await this.database.query(query, scope, options);
       return results;
     } catch (error) {
       throw error;
     }
   }
 
+  getQueryOptions(args = {}) {
+    let scanConsistency = args.scan_consistency;
+
+    // Backward compatibility for callers that already use statement_consistent.
+    // The adapter accepts the SDK-style value as well as these snake_case keys.
+    if (scanConsistency === undefined && args.statement_consistent !== undefined) {
+      const legacyValue = args.statement_consistent;
+      const isRequestPlus =
+        legacyValue === true ||
+        (typeof legacyValue === "string" &&
+          ["true", "request_plus"].includes(legacyValue.toLowerCase()));
+      scanConsistency = isRequestPlus ? "request_plus" : "not_bounded";
+    }
+
+    return {
+      scan_consistency: scanConsistency,
+      consistent_with: args.consistent_with,
+      scan_wait: args.scan_wait,
+    };
+  }
+
+  requiresFreshQuery(args = {}) {
+    const options = this.getQueryOptions(args);
+    const scanConsistency = options.scan_consistency;
+    return (
+      options.consistent_with !== undefined ||
+      scanConsistency === true ||
+      (typeof scanConsistency === "string" &&
+        ["true", "request_plus"].includes(scanConsistency.toLowerCase()))
+    );
+  }
+
   async getMulti(args) {
     // ⚡ Profiling: use track() for proper async context forking
     const p = this[_ctx]?.profiler;
@@ -1498,10 +1601,10 @@ export default class SpiceModel {
         await this.run_hook(this, "list", "before");
       }
 
-      const cacheKey = `list::${this.type}::${args._join}::${query}::${args.limit}::${args.offset}::${args.sort}::${args.do_count}::${args.statement_consistent}::${args.columns}::${args.is_full_text}::${args.is_custom_query}`;
+      const cacheKey = `list::${this.type}::${args._join}::${query}::${args.limit}::${args.offset}::${args.sort}::${args.do_count}::${args.query_scope}::${args.scan_consistency}::${args.statement_consistent}::${args.scan_wait}::${args.columns}::${args.is_full_text}::${args.is_custom_query}`;
       let results;
 
-      if (this.shouldUseCache(this.type)) {
+      if (this.shouldUseCache(this.type) && !this.requiresFreshQuery(args)) {
         const cached = await this.getCacheProviderObject(this.type).get(
           cacheKey,
         );
@@ -1600,6 +1703,7 @@ export default class SpiceModel {
     const p = this[_ctx]?.profiler;
 
     const doFetch = async () => {
+      const queryOptions = this.getQueryOptions(args);
       if (args.is_custom_query === "true" && args.ids.length > 0) {
         console.log(
           "Fetching results from database",
@@ -1608,7 +1712,7 @@ export default class SpiceModel {
           query,
           mappedNestings,
         );
-        return await this.database.query(query);
+        return await this.database.query(query, args.query_scope, queryOptions);
       } else if (args.is_full_text === "true") {
         return await this.database.full_text_search(
           this.type,
@@ -1630,8 +1734,9 @@ export default class SpiceModel {
           args.offset,
           args.sort,
           args.do_count,
-          args.statement_consistent,
+          args.query_scope,
           args._join,
+          queryOptions,
         );
         return result;
       }
@@ -1815,6 +1920,8 @@ export default class SpiceModel {
               mapping_dept: this[_mapping_dept],
               mapping_dept_scalar: this[_mapping_dept_scalar],
               mapping_dept_array: this[_mapping_dept_array],
+              mapping_concurrency: this[_mapping_concurrency],
+              skip_mapped_serialization: this[_skip_mapped_serialization],
               mapping_dept_exempt: this[_mapping_dept_exempt],
               _columns: columnArray.join(","),
               _current_path: childPath,
@@ -1824,6 +1931,7 @@ export default class SpiceModel {
               skip_hooks: true,
               ids: ids,
               columns: columnArray,
+              skip_read_serialize: this[_skip_mapped_serialization],
             });
           }),
         );
@@ -1990,6 +2098,8 @@ export default class SpiceModel {
               mapping_dept: this[_mapping_dept],
               mapping_dept_scalar: this[_mapping_dept_scalar],
               mapping_dept_array: this[_mapping_dept_array],
+              mapping_concurrency: this[_mapping_concurrency],
+              skip_mapped_serialization: this[_skip_mapped_serialization],
               mapping_dept_exempt: this[_mapping_dept_exempt],
               _columns: columnArray.join(","),
               _current_path: childPath,
@@ -1997,6 +2107,7 @@ export default class SpiceModel {
               skip_hooks: true,
               ids: ids,
               columns: columnArray,
+              skip_read_serialize: this[_skip_mapped_serialization],
             });
           }),
         );
@@ -2070,8 +2181,21 @@ export default class SpiceModel {
     return original_is_array ? data : data[0];
   }
 
-  addModifier({ when, execute }) {
+  addModifier({
+    when,
+    execute,
+    kind,
+    source_property,
+    store_property,
+  }) {
     if (this[_serializers][when]) {
+      if (kind) {
+        execute.spiceModifier = {
+          kind,
+          source_property,
+          store_property,
+        };
+      }
       this[_serializers][when]["modifiers"].push(execute);
     }
   }
@@ -2145,6 +2269,9 @@ export default class SpiceModel {
               case "string": {
                 this.addModifier({
                   when: properties[i].map.when || "read",
+                  kind: "relationship_map",
+                  source_property: i,
+                  store_property: properties[i].map.destination || i,
                   execute: async (
                     data,
                     old_data,
@@ -2182,6 +2309,9 @@ export default class SpiceModel {
               case "array": {
                 this.addModifier({
                   when: properties[i].map.when || "read",
+                  kind: "relationship_map",
+                  source_property: i,
+                  store_property: properties[i].map.destination || i,
                   execute: async (
                     data,
                     old_data,
@@ -2245,11 +2375,10 @@ export default class SpiceModel {
 
       // Cache the modifiers lookup for the specified type.
       const modifiers = this[_serializers]?.[type]?.modifiers || [];
-      for (let i = 0; i < modifiers.length; i++) {
-        const modifier = modifiers[i];
+      const invokeModifier = async (modifier, index, inputData) => {
         try {
           const result = await modifier(
-            data,
+            inputData,
             old_data,
             this[_ctx],
             this.type,
@@ -2259,22 +2388,117 @@ export default class SpiceModel {
             this[_columns],
             type,
           );
-          // Guard against modifiers that return undefined
           if (result !== undefined) {
-            data = result;
-          } else {
-            console.warn(
-              `Modifier #${i} for type=${this.type} returned undefined, keeping previous data`,
-            );
+            return { hasValue: true, value: result };
           }
+          console.warn(
+            `Modifier #${index} for type=${this.type} returned undefined, keeping previous data`,
+          );
         } catch (error) {
           console.error(
-            `Modifier error in do_serialize (type=${this.type}, modifier #${i}):`,
+            `Modifier error in do_serialize (type=${this.type}, modifier #${index}):`,
             error instanceof Error ?
               error.stack
             : `Non-Error thrown: ${JSON.stringify(error)}`,
           );
         }
+        return { hasValue: false };
+      };
+
+      let modifierIndex = 0;
+      while (modifierIndex < modifiers.length) {
+        const modifier = modifiers[modifierIndex];
+        const canRunRelationshipMapsConcurrently =
+          type === "read" &&
+          this[_level] === 0 &&
+          this[_mapping_concurrency] > 1 &&
+          modifier?.spiceModifier?.kind === "relationship_map";
+
+        if (!canRunRelationshipMapsConcurrently) {
+          const result = await invokeModifier(modifier, modifierIndex, data);
+          if (result.hasValue) data = result.value;
+          modifierIndex += 1;
+          continue;
+        }
+
+        const group = [];
+        const destinations = new Set();
+        while (modifierIndex < modifiers.length) {
+          const candidate = modifiers[modifierIndex];
+          const metadata = candidate?.spiceModifier;
+          if (metadata?.kind !== "relationship_map") break;
+          if (
+            metadata.store_property &&
+            destinations.has(metadata.store_property)
+          ) {
+            break;
+          }
+          if (metadata.store_property) {
+            destinations.add(metadata.store_property);
+          }
+          group.push({ modifier: candidate, index: modifierIndex, metadata });
+          modifierIndex += 1;
+        }
+
+        const groupQueuedAt = process.hrtime.bigint();
+        let activeRequestMappings = 0;
+        const executeGroup = async () =>
+          await runWithConcurrency(
+            group,
+            this[_mapping_concurrency],
+            async (entry) => {
+              const requestQueueWaitMs =
+                Number(process.hrtime.bigint() - groupQueuedAt) / 1e6;
+              const globalSlot = await acquireGlobalMappingSlot();
+              activeRequestMappings += 1;
+              const profileMetadata = {
+                source_property: entry.metadata.source_property,
+                store_property: entry.metadata.store_property,
+                request_queue_wait_ms:
+                  Math.round(requestQueueWaitMs * 100) / 100,
+                global_queue_wait_ms:
+                  Math.round(globalSlot.waitMs * 100) / 100,
+                active_request_mappings: activeRequestMappings,
+                request_limit: this[_mapping_concurrency],
+                active_global_mappings: globalSlot.active,
+                global_limit: GLOBAL_MAPPING_CONCURRENCY,
+              };
+
+              try {
+                const execute = async () =>
+                  await invokeModifier(entry.modifier, entry.index, data);
+                if (p) {
+                  return await p.track(
+                    `${this.type}.map.concurrent.${entry.metadata.source_property}`,
+                    execute,
+                    profileMetadata,
+                  );
+                }
+                return await execute();
+              } finally {
+                activeRequestMappings -= 1;
+                globalSlot.release();
+              }
+            },
+          );
+
+        const groupMetadata = {
+          map_count: group.length,
+          request_limit: this[_mapping_concurrency],
+          global_limit: GLOBAL_MAPPING_CONCURRENCY,
+        };
+        const groupResults =
+          p ?
+            await p.track(
+              `${this.type}.map.concurrent`,
+              executeGroup,
+              groupMetadata,
+            )
+          : await executeGroup();
+
+        for (const result of groupResults) {
+          if (result?.hasValue) data = result.value;
+        }
       }
 
       // Ensure data is always an array for consistent processing.

package/tests/models/SpiceModel.mapping-depth.test.js

@@ -7,7 +7,9 @@ describe('SpiceModel type-specific mapping depth', () => {
         capture.constructorArgs.push(args);
       }
 
-      async getMulti({ ids }) {
+      async getMulti(args) {
+        const { ids } = args;
+        capture.getMultiArgs.push(args);
         capture.getMultiIds.push(ids);
         return records.filter((record) => ids.includes(record.id));
       }
@@ -15,8 +17,16 @@ describe('SpiceModel type-specific mapping depth', () => {
   }
 
   function createMappedModel(args = {}) {
-    const scalarCapture = { constructorArgs: [], getMultiIds: [] };
-    const arrayCapture = { constructorArgs: [], getMultiIds: [] };
+    const scalarCapture = {
+      constructorArgs: [],
+      getMultiArgs: [],
+      getMultiIds: [],
+    };
+    const arrayCapture = {
+      constructorArgs: [],
+      getMultiArgs: [],
+      getMultiIds: [],
+    };
     const ScalarModel = createRelatedModel(
       [{ id: 'group-1', name: 'Administrators' }],
       scalarCapture
@@ -51,6 +61,41 @@ describe('SpiceModel type-specific mapping depth', () => {
     return { model, scalarCapture, arrayCapture };
   }
 
+  function createConcurrencyModel(mappingConcurrency, extraArgs = {}) {
+    const stats = { active: 0, maxActive: 0 };
+    class RelatedModel {
+      async getMulti({ ids }) {
+        stats.active += 1;
+        stats.maxActive = Math.max(stats.maxActive, stats.active);
+        await new Promise((resolve) => setImmediate(resolve));
+        stats.active -= 1;
+        return ids.map((id) => ({ id, name: id }));
+      }
+    }
+
+    const props = {};
+    const record = { id: 'parent-concurrent', type: 'parent' };
+    for (let index = 1; index <= 3; index += 1) {
+      const field = `relationship_${index}`;
+      props[field] = {
+        type: 'string',
+        map: { type: 'model', reference: RelatedModel }
+      };
+      record[field] = `related-${index}`;
+    }
+
+    const model = createTestModel({
+      type: 'parent',
+      args: {
+        ...extraArgs,
+        ...(mappingConcurrency ? { mapping_concurrency: mappingConcurrency } : {})
+      },
+      props
+    });
+    seedDatabase(model, record);
+    return { model, stats };
+  }
+
   test('uses scalar depth 1 and array depth 3 from the request profile', async () => {
     const ctx = {
       state: {
@@ -127,7 +172,8 @@ describe('SpiceModel type-specific mapping depth', () => {
   test('propagates both depths to related model instances', async () => {
     const { model, arrayCapture } = createMappedModel({
       mapping_dept_scalar: 1,
-      mapping_dept_array: 3
+      mapping_dept_array: 3,
+      mapping_concurrency: 6
     });
 
     await model.getMulti({ ids: ['parent-1'] });
@@ -136,13 +182,105 @@ describe('SpiceModel type-specific mapping depth', () => {
       expect.objectContaining({
         mapping_dept_scalar: 1,
         mapping_dept_array: 3,
+        mapping_concurrency: 6,
         _level: 1
       })
     );
   });
 
+  test('runs independent relationship maps with bounded concurrency', async () => {
+    const { model, stats } = createConcurrencyModel(2);
+
+    const result = await model.get({ id: 'parent-concurrent' });
+
+    expect(stats.maxActive).toBe(2);
+    expect(result.relationship_1).toEqual(
+      expect.objectContaining({ id: 'related-1' })
+    );
+    expect(result.relationship_3).toEqual(
+      expect.objectContaining({ id: 'related-3' })
+    );
+  });
+
+  test('keeps relationship maps sequential when concurrency is not enabled', async () => {
+    const { model, stats } = createConcurrencyModel();
+
+    await model.get({ id: 'parent-concurrent' });
+
+    expect(stats.maxActive).toBe(1);
+  });
+
+  test('keeps nested relationship maps sequential to avoid recursive slot use', async () => {
+    const { model, stats } = createConcurrencyModel(2, { _level: 1 });
+
+    await model.get({ id: 'parent-concurrent' });
+
+    expect(stats.maxActive).toBe(1);
+  });
+
+  test('profiles concurrent groups and mapping slot pressure', async () => {
+    const calls = [];
+    const profiler = {
+      track: jest.fn(async (name, execute, metadata) => {
+        calls.push({ name, metadata });
+        return await execute();
+      })
+    };
+    const { model } = createConcurrencyModel(2, { ctx: { profiler } });
+
+    await model.get({ id: 'parent-concurrent' });
+
+    expect(calls).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: 'parent.map.concurrent',
+          metadata: expect.objectContaining({
+            map_count: 3,
+            request_limit: 2
+          })
+        }),
+        expect.objectContaining({
+          name: 'parent.map.concurrent.relationship_1',
+          metadata: expect.objectContaining({
+            request_limit: 2,
+            active_request_mappings: expect.any(Number),
+            active_global_mappings: expect.any(Number),
+            request_queue_wait_ms: expect.any(Number),
+            global_queue_wait_ms: expect.any(Number)
+          })
+        })
+      ])
+    );
+  });
+
+  test('skips serialization for mapped child reads when requested by the profile', async () => {
+    const ctx = {
+      state: {
+        read_profile: {
+          mapping_dept_scalar: 2,
+          mapping_dept_array: 3,
+          skip_mapped_serialization: true
+        }
+      }
+    };
+    const { model, scalarCapture, arrayCapture } = createMappedModel({ ctx });
+
+    const result = await model.get({ id: 'parent-1' });
+
+    expect(result.group).toEqual(
+      expect.objectContaining({ id: 'group-1', name: 'Administrators' })
+    );
+    expect(result.children).toHaveLength(2);
+    expect(scalarCapture.getMultiArgs[0]).toEqual(
+      expect.objectContaining({ skip_hooks: true, skip_read_serialize: true })
+    );
+    expect(arrayCapture.getMultiArgs[0]).toEqual(
+      expect.objectContaining({ skip_hooks: true, skip_read_serialize: true })
+    );
+  });
+
   test('does not apply the request read profile to write serialization', async () => {
-    const capture = { constructorArgs: [], getMultiIds: [] };
+    const capture = { constructorArgs: [], getMultiArgs: [], getMultiIds: [] };
     const RelatedModel = createRelatedModel(
       [{ id: 'group-1', name: 'Administrators' }],
       capture

package/tests/models/SpiceModel.query-consistency.test.js

@@ -0,0 +1,114 @@
+const { createTestModel } = require("../helpers/modelFactory");
+
+describe("SpiceModel query consistency", () => {
+  test("keeps query scope separate from query consistency", async () => {
+    const model = createTestModel({ type: "application" });
+    model.database.search = jest.fn(async () => ({ data: [], total: null }));
+
+    await model.fetchResults(
+      {
+        ids: [],
+        query_scope: "cluster",
+        scan_consistency: "request_plus",
+        scan_wait: 2500,
+        _join: "",
+      },
+      "",
+      [],
+    );
+
+    expect(model.database.search).toHaveBeenCalledWith(
+      "application",
+      "",
+      "",
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      "cluster",
+      "",
+      {
+        scan_consistency: "request_plus",
+        consistent_with: undefined,
+        scan_wait: 2500,
+      },
+    );
+  });
+
+  test.each([true, "true", "request_plus"])(
+    "maps legacy statement_consistent=%s to request_plus",
+    (legacyValue) => {
+      const model = createTestModel({ type: "application" });
+
+      expect(
+        model.getQueryOptions({ statement_consistent: legacyValue }),
+      ).toEqual(
+        expect.objectContaining({ scan_consistency: "request_plus" }),
+      );
+    },
+  );
+
+  test.each([false, "false"])(
+    "maps legacy statement_consistent=%s to not_bounded",
+    (legacyValue) => {
+      const model = createTestModel({ type: "application" });
+
+      expect(
+        model.getQueryOptions({ statement_consistent: legacyValue }),
+      ).toEqual(
+        expect.objectContaining({ scan_consistency: "not_bounded" }),
+      );
+    },
+  );
+
+  test("explicit scan_consistency takes precedence over the legacy flag", () => {
+    const model = createTestModel({ type: "application" });
+
+    expect(
+      model.getQueryOptions({
+        scan_consistency: "not_bounded",
+        statement_consistent: true,
+      }),
+    ).toEqual(expect.objectContaining({ scan_consistency: "not_bounded" }));
+  });
+
+  test("strongly consistent reads bypass the model query cache", () => {
+    const model = createTestModel({ type: "application" });
+
+    expect(model.requiresFreshQuery({ scan_consistency: "request_plus" })).toBe(
+      true,
+    );
+    expect(model.requiresFreshQuery({ statement_consistent: true })).toBe(true);
+    expect(model.requiresFreshQuery({ consistent_with: {} })).toBe(true);
+    expect(model.requiresFreshQuery({ scan_consistency: "not_bounded" })).toBe(
+      false,
+    );
+  });
+
+  test("custom queries receive the same query options", async () => {
+    const model = createTestModel({ type: "application" });
+    model.database.query = jest.fn(async () => ({ rows: [] }));
+    const mutationState = { token: "test-token" };
+
+    await model.fetchResults(
+      {
+        ids: ["application-1"],
+        is_custom_query: "true",
+        query_scope: "scope",
+        consistent_with: mutationState,
+      },
+      "SELECT 1",
+      [],
+    );
+
+    expect(model.database.query).toHaveBeenCalledWith(
+      "SELECT 1",
+      "scope",
+      {
+        scan_consistency: undefined,
+        consistent_with: mutationState,
+        scan_wait: undefined,
+      },
+    );
+  });
+});