@contrail/util 1.3.3-alpha.7783621 → 1.4.0-alpha.ebd7d81

package/CHANGELOG.md

@@ -7,11 +7,14 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [1.3.3] - 2026-09-03
+## [1.4.0] - 2026-09-11
 
-### Fixed
+### Added
 
-- `ObjectUtil.mergeDeep` no longer discards a value when the target cannot be merged into. An incoming object landing on an existing array, string, or number replaces it, instead of being silently skipped. Merging two objects is unchanged: keys the source omits still survive.
+- `response-size-util` — measures whether a payload fits within AWS Lambda's 6MB response limit, so services can decide to offload to S3 based on actual serialized bytes rather than a row count.
+  - `exceedsResponseBudget(value, options?)` — the decision helper. For arrays it serializes one element at a time and stops as soon as the budget is crossed, so the cost is bounded by the budget rather than by the size of the payload.
+  - `getJsonByteLength(value)` / `getUtf8ByteLength(str)` — exact UTF-8 byte measurement.
+  - `getResponseBudgetBytes(options?)`, `LAMBDA_MAX_RESPONSE_BYTES`, `DEFAULT_RESPONSE_BUFFER_BYTES` — the budget and its defaults (6MB ceiling, 512KB buffer).
 
 ## [1.2.1] - 2026-03-25
 

package/lib/index.d.ts

@@ -6,6 +6,7 @@ export * from './object-util/object-util';
 export * from './order-util/order-util';
 export * from './performance-util/performance-util';
 export * from './promise-util/promise-util';
+export * from './response-size-util/response-size-util';
 export * from './retry-util/retry-util';
 export * from './string-util/string-util';
 export * from './timer-util/timer-util';

package/lib/index.js

@@ -22,6 +22,7 @@ __exportStar(require("./object-util/object-util"), exports);
 __exportStar(require("./order-util/order-util"), exports);
 __exportStar(require("./performance-util/performance-util"), exports);
 __exportStar(require("./promise-util/promise-util"), exports);
+__exportStar(require("./response-size-util/response-size-util"), exports);
 __exportStar(require("./retry-util/retry-util"), exports);
 __exportStar(require("./string-util/string-util"), exports);
 __exportStar(require("./timer-util/timer-util"), exports);

package/lib/object-util/mergeDeep/mergeDeep.js

@@ -9,7 +9,7 @@ function mergeDeep(target, ...sources) {
     if ((0, isObject_1.isObject)(target) && (0, isObject_1.isObject)(source)) {
         for (const key in source) {
             if ((0, isObject_1.isObject)(source[key]) && !isDate(source[key])) {
-                if (!(0, isObject_1.isObject)(target[key]))
+                if (!target[key])
                     Object.assign(target, { [key]: {} });
                 mergeDeep(target[key], source[key]);
             }

package/lib/response-size-util/response-size-util.d.ts

@@ -0,0 +1,10 @@
+export declare const LAMBDA_MAX_RESPONSE_BYTES: number;
+export declare const DEFAULT_RESPONSE_BUFFER_BYTES: number;
+export interface ResponseBudgetOptions {
+    maxBytes?: number;
+    bufferBytes?: number;
+}
+export declare function getResponseBudgetBytes(options?: ResponseBudgetOptions): number;
+export declare function getUtf8ByteLength(str: string): number;
+export declare function getJsonByteLength(value: unknown): number;
+export declare function exceedsResponseBudget(value: unknown, options?: ResponseBudgetOptions): boolean;

package/lib/response-size-util/response-size-util.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RESPONSE_BUFFER_BYTES = exports.LAMBDA_MAX_RESPONSE_BYTES = void 0;
+exports.getResponseBudgetBytes = getResponseBudgetBytes;
+exports.getUtf8ByteLength = getUtf8ByteLength;
+exports.getJsonByteLength = getJsonByteLength;
+exports.exceedsResponseBudget = exceedsResponseBudget;
+exports.LAMBDA_MAX_RESPONSE_BYTES = 6 * 1024 * 1024;
+exports.DEFAULT_RESPONSE_BUFFER_BYTES = 0.5 * 1024 * 1024;
+function getResponseBudgetBytes(options = {}) {
+    var _a, _b;
+    const maxBytes = (_a = options.maxBytes) !== null && _a !== void 0 ? _a : exports.LAMBDA_MAX_RESPONSE_BYTES;
+    const bufferBytes = (_b = options.bufferBytes) !== null && _b !== void 0 ? _b : exports.DEFAULT_RESPONSE_BUFFER_BYTES;
+    return Math.max(0, maxBytes - bufferBytes);
+}
+function getUtf8ByteLength(str) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.byteLength(str, 'utf8');
+    }
+    return new TextEncoder().encode(str).length;
+}
+function getJsonByteLength(value) {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? 0 : getUtf8ByteLength(serialized);
+}
+function exceedsResponseBudget(value, options = {}) {
+    const budgetBytes = getResponseBudgetBytes(options);
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (!Array.isArray(value)) {
+        return getJsonByteLength(value) > budgetBytes;
+    }
+    if (value.length === 0) {
+        return false;
+    }
+    let totalBytes = 2 + (value.length - 1);
+    for (const element of value) {
+        if (totalBytes > budgetBytes) {
+            return true;
+        }
+        const serialized = JSON.stringify(element);
+        totalBytes += serialized === undefined ? 4 : getUtf8ByteLength(serialized);
+    }
+    return totalBytes > budgetBytes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/util",
-  "version": "1.3.3-alpha.7783621",
+  "version": "1.4.0-alpha.ebd7d81",
   "description": "General JavaScript utilities",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",