@contrail/util 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -14,6 +14,22 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - `RESPONSE_BYTE_LIMIT` — the cap minus the buffer, in bytes, for size checks that work in bytes.
   - `getSerializedByteSize` — serialized byte size of any value. Treats `undefined` as `null`, since `JSON.stringify(undefined)` returns `undefined` rather than a string and `Buffer.byteLength` throws on it.
 
+## [1.5.0] - 2026-09-25
+
+Maintenance release on the 1.x line; the same changes ship on 2.x as 2.2.0 and 2.2.1.
+
+### Added
+
+- `response-size-util` — measures whether a payload fits within the AWS Lambda 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?)` — the budget a measured payload must stay under.
+  - `LAMBDA_MAX_RESPONSE_BYTES`, `RESPONSE_GUARD_LIMIT_BYTES`, `DEFAULT_RESPONSE_BUFFER_BYTES`, `DEFAULT_RESPONSE_BUDGET_BYTES` — the ladder of thresholds a response crosses, each sitting below the one above it so a payload offloads before `core`'s response guard returns a 413, and the guard fires before Lambda rejects the invocation.
+
+### Fixed
+
+- `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.
+
 ## [1.2.1] - 2026-03-25
 
 ### Added

package/lib/index.d.ts

@@ -7,6 +7,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

@@ -23,6 +23,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 (!target[key])
+                if (!(0, isObject_1.isObject)(target[key]))
                     Object.assign(target, { [key]: {} });
                 mergeDeep(target[key], source[key]);
             }

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

@@ -0,0 +1,12 @@
+export declare const LAMBDA_MAX_RESPONSE_BYTES = 6000000;
+export declare const RESPONSE_GUARD_LIMIT_BYTES = 5500000;
+export declare const DEFAULT_RESPONSE_BUFFER_BYTES = 500000;
+export declare const DEFAULT_RESPONSE_BUDGET_BYTES: number;
+export interface ResponseBudgetOptions {
+    limitBytes?: 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,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RESPONSE_BUDGET_BYTES = exports.DEFAULT_RESPONSE_BUFFER_BYTES = exports.RESPONSE_GUARD_LIMIT_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 = 6000000;
+exports.RESPONSE_GUARD_LIMIT_BYTES = 5500000;
+exports.DEFAULT_RESPONSE_BUFFER_BYTES = 500000;
+exports.DEFAULT_RESPONSE_BUDGET_BYTES = exports.RESPONSE_GUARD_LIMIT_BYTES - exports.DEFAULT_RESPONSE_BUFFER_BYTES;
+const JSON_NULL_BYTES = 'null'.length;
+function getResponseBudgetBytes(options = {}) {
+    var _a, _b;
+    const limitBytes = (_a = options.limitBytes) !== null && _a !== void 0 ? _a : exports.RESPONSE_GUARD_LIMIT_BYTES;
+    const bufferBytes = (_b = options.bufferBytes) !== null && _b !== void 0 ? _b : exports.DEFAULT_RESPONSE_BUFFER_BYTES;
+    return Math.max(0, limitBytes - 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;
+    }
+    const bracketBytes = '[]'.length;
+    const separatorBytes = value.length - 1;
+    let totalBytes = bracketBytes + separatorBytes;
+    for (const element of value) {
+        if (totalBytes > budgetBytes) {
+            return true;
+        }
+        const serialized = JSON.stringify(element);
+        totalBytes += serialized === undefined ? JSON_NULL_BYTES : getUtf8ByteLength(serialized);
+    }
+    return totalBytes > budgetBytes;
+}

package/package.json

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