@contrail/util 2.1.0 → 2.2.0-alpha.3804ed9

package/CHANGELOG.md

@@ -14,6 +14,15 @@ 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.
 
+## [2.2.0] - 2026-09-14
+
+### Added
+
+- `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
 
 ### 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/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": "2.1.0",
+  "version": "2.2.0-alpha.3804ed9",
   "description": "General JavaScript utilities",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",