@encodeagent/platform-helper-util 1.2603.1221241 → 1.2603.1311450

package/dist/core.js

@@ -484,6 +484,13 @@ const ttl = (mins = 60) => {
     return (0, exports.unixTimestamp)() + mins * 60;
 };
 exports.ttl = ttl;
+/**
+ * Evaluates a JS expression string against `props` using the caller-supplied
+ * `props.jsEvalFunction` compiler. Returns true when the expression or the
+ * function it produces is truthy.
+ * @param js - JavaScript expression string to evaluate
+ * @param props - Context object; must provide `jsEvalFunction(js)` to compile `js`
+ */
 const checkToTrue = (js, props) => {
     if (!(0, lodash_1.isObject)(props))
         props = {};
@@ -506,6 +513,12 @@ const checkToTrue = (js, props) => {
     return false;
 };
 exports.checkToTrue = checkToTrue;
+/**
+ * Validates whether a string is a correctly formatted email address.
+ * Leading/trailing whitespace and `+` characters are stripped before matching.
+ * @param s - Value to validate
+ * @param allowNilEmpty - When true, null/empty values are considered valid
+ */
 const isEmail = (s, allowNilEmpty) => {
     if (allowNilEmpty && !(0, exports.isNonEmptyString)(s))
         return true;
@@ -518,6 +531,13 @@ const isEmail = (s, allowNilEmpty) => {
     return pattern.test(email);
 };
 exports.isEmail = isEmail;
+/**
+ * Validates a password against configurable complexity rules. Defaults are
+ * sourced from `DEFAULT_PASSWORD_RULE` and can be overridden via `settings`.
+ * @param s - Password string to validate
+ * @param settings - Complexity overrides (minLen, needDigit, needUpperCaseLetter, etc.)
+ * @returns true when all active rules pass
+ */
 const isPassword = (s, settings) => {
     if (!(0, lodash_1.isObject)(settings))
         settings = {};
@@ -560,14 +580,29 @@ const isPassword = (s, settings) => {
     return result;
 };
 exports.isPassword = isPassword;
+/**
+ * Returns a Unix-epoch millisecond timestamp.
+ * Uses the provided date when given, otherwise returns the current time.
+ * @param dt - Optional date to convert (defaults to `new Date()`)
+ */
 const getTimestamp = (dt) => {
     return dt ? new Date(dt).getTime() : new Date().getTime();
 };
 exports.getTimestamp = getTimestamp;
+/**
+ * Returns the maximum representable UTC timestamp in milliseconds (year 9999).
+ * Useful as a sentinel "no expiry" value in date-range queries.
+ */
 const getMaxTimestamp = () => {
     return new Date("9999-12-31T23:59:59.999Z").getTime();
 };
 exports.getMaxTimestamp = getMaxTimestamp;
+/**
+ * Returns an ISO 8601 UTC string for a given date, optionally shifted by `minutesDiff` minutes.
+ * Defaults to the current time when `dt` is omitted.
+ * @param dt - Base date (defaults to `new Date()`)
+ * @param minutesDiff - Minutes to add or subtract from the base date
+ */
 const getUTCISOString = (dt, minutesDiff) => {
     if (!dt)
         dt = new Date();
@@ -578,10 +613,20 @@ const getUTCISOString = (dt, minutesDiff) => {
     return dt.toISOString();
 };
 exports.getUTCISOString = getUTCISOString;
+/**
+ * Returns the maximum representable UTC datetime as an ISO 8601 string ("9999-12-31T23:59:59.999Z").
+ * Use as a "no expiry" sentinel in time-bounded queries.
+ */
 const getUTCMaxISOString = () => {
     return (0, exports.getUTCISOString)(new Date("9999-12-31T23:59:59.999Z"), 0);
 };
 exports.getUTCMaxISOString = getUTCMaxISOString;
+/**
+ * Simple positional string formatter. The first argument is the template; each
+ * subsequent argument replaces the next `{0}` placeholder in the template.
+ * Returns `null` when no arguments are provided.
+ * @example formatString('Hello {0}!', 'World') // 'Hello World!'
+ */
 const formatString = (...args) => {
     if (args.length == 0)
         return null;
@@ -592,16 +637,29 @@ const formatString = (...args) => {
     return s;
 };
 exports.formatString = formatString;
+/**
+ * Truncates `s` to `l` characters, appending ` ...` when the string exceeds the limit.
+ * Returns `s` unchanged when it is already within the limit.
+ */
 const shortenString = (s, l) => {
     return s.length <= l ? s : `${s.substring(0, l)} ...`;
 };
 exports.shortenString = shortenString;
-//the isObject from lodash will cause error from typescript
-//this one will not
+// TypeScript-safe wrapper — lodash's isObject causes TS type-narrowing errors
+// when the result is used as a boolean; this wrapper avoids that by always returning boolean.
+/**
+ * Returns `true` when `v` is any non-primitive value (object, array, function).
+ * Wraps lodash `isObject` in a way that avoids TypeScript type-narrowing issues.
+ */
 const isObject = (v) => {
     return (0, lodash_1.isObject)(v) ? true : false;
 };
 exports.isObject = isObject;
+/**
+ * Returns `true` when `s` is a valid JSON string that parses without error.
+ * Note: this accepts any valid JSON value (string, number, array, object).
+ * Use `isGoodJSON` for a nil-safe alternative.
+ */
 const isObjectString = (s) => {
     try {
         JSON.parse(s);
@@ -612,6 +670,13 @@ const isObjectString = (s) => {
     }
 };
 exports.isObjectString = isObjectString;
+/**
+ * Recursively removes properties with `null` or `undefined` values from an object or array.
+ * When `removeEmptyString` is true, empty string values are also removed.
+ * Mutates the input object/array in place and also returns it.
+ * @param data - Object or array to clean
+ * @param removeEmptyString - Whether to remove `""` values in addition to null/undefined
+ */
 const removeNoValueProperty = (data, removeEmptyString) => {
     if ((0, lodash_1.isArray)(data)) {
         return (0, lodash_1.without)((0, lodash_1.map)(data, (r) => {
@@ -651,6 +716,16 @@ const removeNoValueProperty = (data, removeEmptyString) => {
     return data;
 };
 exports.removeNoValueProperty = removeNoValueProperty;
+/**
+ * Groups an array of items under their corresponding group definitions.
+ * Each group in the result gains a `data` property containing its items,
+ * sorted by `propNameForItemSort` (default: `"fullName"`).
+ * Items whose group property does not match any group are omitted.
+ * @param data - Flat list of items to group
+ * @param groups - Group definitions (each must have an `id` field)
+ * @param propNameForItemGroup - Property on each item that identifies its group id (default: `"group"`)
+ * @param propNameForItemSort - Property used to sort items within each group (default: `"fullName"`)
+ */
 const groupItems = (data, groups, propNameForItemGroup, propNameForItemSort) => {
     if (!((0, lodash_1.isArray)(data) && data.length > 0))
         return [];
@@ -676,6 +751,12 @@ const groupItems = (data, groups, propNameForItemGroup, propNameForItemSort) =>
     return result;
 };
 exports.groupItems = groupItems;
+/**
+ * Formats a large number with a compact suffix (K, M, B, T, P, E).
+ * @param num - Number to format
+ * @param fractionDigits - Decimal places to show (default: 1, clamped to ≥ 0)
+ * @example shortenNumber(1500) // '1.5K'
+ */
 const shortenNumber = (num, fractionDigits) => {
     if (!(0, lodash_1.isNumber)(fractionDigits) ||
         ((0, lodash_1.isNumber)(fractionDigits) && fractionDigits < 0))
@@ -701,6 +782,13 @@ const shortenNumber = (num, fractionDigits) => {
         : "0";
 };
 exports.shortenNumber = shortenNumber;
+/**
+ * Collection of `Intl.NumberFormat`-based formatting functions for the US locale.
+ * - `number` — decimal number with optional compact notation
+ * - `currency` — monetary value with currency symbol (default USD)
+ * - `unit` — plain decimal (no currency/percent)
+ * - `percentage` — percent with sign prefix for positive values
+ */
 exports.formatters = {
     number: ({ number, minFractionDigits = 0, maxFractionDigits = 2, compact = false }) => new Intl.NumberFormat("en-US", {
         minimumFractionDigits: minFractionDigits,
@@ -730,6 +818,14 @@ exports.formatters = {
         return `${symbol}${formattedNumber}`;
     }
 };
+/**
+ * Transforms `text` according to the chosen `format` mode:
+ * - `"lower"` / `"upper"` — case conversion
+ * - `"capital"` / `"capital-first"` — capitalises the first word
+ * - `"capital-all"` — capitalises every word
+ * - `"camel"` — converts to camelCase
+ * - `"initials"` — first character of each space-separated word
+ */
 const formatText = (text, format) => {
     switch (format) {
         case "lower":
@@ -750,6 +846,10 @@ const formatText = (text, format) => {
     }
 };
 exports.formatText = formatText;
+/**
+ * Converts a raw byte count into a human-readable size string (e.g. "1.5 MB").
+ * Returns an empty string when the input is not a number.
+ */
 const readableFileSize = (fileSizeInBytes) => {
     if (!(0, lodash_1.isNumber)(fileSizeInBytes))
         return "";
@@ -762,6 +862,11 @@ const readableFileSize = (fileSizeInBytes) => {
     return Math.max(fileSizeInBytes, 0.1).toFixed(1) + byteUnits[i];
 };
 exports.readableFileSize = readableFileSize;
+/**
+ * Pretty-prints a JSON string with 4-space indentation.
+ * Parses the input first; if the parse produces a non-serialisable value,
+ * falls back to compact `JSON.stringify`.
+ */
 const formatJSONString = (c) => {
     const jsonValue = (0, exports.isNonEmptyString)(c) ? JSON.parse(c) : c;
     try {
@@ -773,6 +878,11 @@ const formatJSONString = (c) => {
     return JSON.stringify(jsonValue);
 };
 exports.formatJSONString = formatJSONString;
+/**
+ * Recursively flattens a deeply nested array into a single flat array.
+ * @param array - Potentially nested array to flatten
+ * @example deepFlatten([1, [2, [3, [4]]]]) // [1, 2, 3, 4]
+ */
 const deepFlatten = (array) => {
     let result = [];
     array.forEach(function (elem) {
@@ -786,6 +896,12 @@ const deepFlatten = (array) => {
     return result;
 };
 exports.deepFlatten = deepFlatten;
+/**
+ * Looks up a country by its ISO 2-letter code, ISO 3-letter code, or full name (case-insensitive).
+ * Returns `undefined` when no match is found.
+ * @param codeOrName - ISO alpha-2/3 code or country name to search for
+ * @param resultFormat - `"PicklistOption"` returns `{ text, value }` for UI dropdowns; default returns the raw country object
+ */
 const findCountry = (codeOrName, resultFormat) => {
     const country = (0, lodash_1.find)(constants_1.COUNTRIES, (c) => {
         return (c.name.toLocaleLowerCase() == codeOrName.toLowerCase() ||
@@ -807,6 +923,11 @@ const findCountry = (codeOrName, resultFormat) => {
     }
 };
 exports.findCountry = findCountry;
+/**
+ * Looks up a gender entry by its display text or value (case-insensitive).
+ * Returns `undefined` when no match is found.
+ * @param textOrValue - Gender text label or value to search for
+ */
 const findGender = (textOrValue) => {
     return (0, lodash_1.find)(constants_1.GENDERS, (c) => {
         return (c.text.toLowerCase() == textOrValue.toLowerCase() ||
@@ -814,6 +935,12 @@ const findGender = (textOrValue) => {
     });
 };
 exports.findGender = findGender;
+/**
+ * Looks up a language by its ISO code or name (case-insensitive, comma-separated names supported).
+ * Returns `undefined` when no match is found.
+ * @param codeOrName - Language ISO code or name to search for
+ * @param resultFormat - `"PicklistOption"` returns `{ text, value }` for UI dropdowns; default returns the raw language object
+ */
 const findLanguage = (codeOrName, resultFormat) => {
     const language = (0, lodash_1.find)(constants_1.LANGUAGES, (c) => {
         let found = c.name.toLowerCase() == codeOrName.trim().toLowerCase() ||
@@ -844,6 +971,13 @@ const findLanguage = (codeOrName, resultFormat) => {
     }
 };
 exports.findLanguage = findLanguage;
+/**
+ * Retrieves a value from the in-memory global cache.
+ * Returns `defaultValue` when the key is absent. When a TTL was set during
+ * `setCache`, expired entries are evicted before the value is returned.
+ * @param key - Cache key to look up
+ * @param defaultValue - Fallback value when the key is missing or expired
+ */
 const getCache = (key, defaultValue) => {
     if (!(0, exports.isNonEmptyString)(key))
         return undefined;
@@ -865,6 +999,13 @@ const getCache = (key, defaultValue) => {
             : undefined;
 };
 exports.getCache = getCache;
+/**
+ * Stores a value in the in-memory global cache.
+ * Passing `null` or `undefined` as `data` removes the key (delegates to `removeCache`).
+ * @param key - Cache key
+ * @param data - Value to store; null/undefined removes the entry
+ * @param expireMinutes - Optional TTL in minutes; omit for no expiry
+ */
 const setCache = (key, data, expireMinutes) => {
     const g = (0, exports.getGlobalObject)();
     if (!(0, exports.isNonEmptyString)(key))
@@ -886,6 +1027,10 @@ const setCache = (key, data, expireMinutes) => {
     }
 };
 exports.setCache = setCache;
+/**
+ * Removes a single entry from the in-memory global cache.
+ * No-ops when the key does not exist.
+ */
 const removeCache = (key) => {
     const g = (0, exports.getGlobalObject)();
     if (!(0, exports.isObject)(g.localCache))
@@ -893,27 +1038,46 @@ const removeCache = (key) => {
     delete g.localCache[key];
 };
 exports.removeCache = removeCache;
+/**
+ * Removes the entire group cache entry for `groupId`, clearing all sub-keys stored under it.
+ */
 const resetCacheByGroupId = (groupId) => {
     (0, exports.removeCache)(groupId);
 };
 exports.resetCacheByGroupId = resetCacheByGroupId;
+/**
+ * Stores a `key → value` pair inside the group cache identified by `groupId`.
+ * The group itself is stored as a single cache entry (an object of sub-keys).
+ */
 const setCacheByGroupId = (groupId, key, value) => {
     const groupCache = (0, exports.getCache)(groupId) ?? {};
     groupCache[key] = value;
     (0, exports.setCache)(groupId, groupCache);
 };
 exports.setCacheByGroupId = setCacheByGroupId;
+/**
+ * Retrieves a `key` from within the group cache identified by `groupId`.
+ * Returns `undefined` when the group or key does not exist.
+ */
 const getCacheByGroupId = (groupId, key) => {
     const groupCache = (0, exports.getCache)(groupId) ?? {};
     return groupCache[key];
 };
 exports.getCacheByGroupId = getCacheByGroupId;
+/**
+ * Removes a single `key` from within the group cache identified by `groupId`.
+ * The group entry itself remains; only the specified sub-key is deleted.
+ */
 const removeCacheByGroupId = (groupId, key) => {
     const groupCache = (0, exports.getCache)(groupId) ?? {};
     delete groupCache[key];
     (0, exports.setCache)(groupId, groupCache);
 };
 exports.removeCacheByGroupId = removeCacheByGroupId;
+/**
+ * Normalises a GUID string by removing curly braces, converting underscores to hyphens,
+ * trimming whitespace, and lowercasing. Returns `""` for falsy input.
+ */
 const cleanGuid = (v) => {
     return !v
         ? ""
@@ -925,14 +1089,28 @@ const cleanGuid = (v) => {
             .toLowerCase();
 };
 exports.cleanGuid = cleanGuid;
+/**
+ * Returns `true` when two GUID strings represent the same identifier after normalisation.
+ * Comparison is case- and formatting-insensitive (braces, underscores, casing all ignored).
+ */
 const sameGuid = (a, b) => {
     return (0, exports.cleanGuid)(a) === (0, exports.cleanGuid)(b);
 };
 exports.sameGuid = sameGuid;
+/**
+ * Returns `true` when `v` equals the all-zeros empty GUID (`00000000-0000-0000-0000-000000000000`).
+ */
 const isEmptyGuid = (v) => {
     return (0, exports.sameGuid)(v, constants_1.GUID_EMPTY);
 };
 exports.isEmptyGuid = isEmptyGuid;
+/**
+ * Converts a TypeScript numeric enum into an array of `{ key, value }` pairs.
+ * TypeScript numeric enums produce double-keyed entries (name ↔ number);
+ * this function returns only the name → value direction.
+ * @param thisEnum - A TypeScript enum object (must be a numeric enum)
+ * @example convertEnumToArray(Direction) // [{ key: 'Up', value: 0 }, ...]
+ */
 const convertEnumToArray = (thisEnum) => {
     let result = [];
     let i = Object.keys(thisEnum).length / 2;
@@ -944,6 +1122,11 @@ const convertEnumToArray = (thisEnum) => {
     return result;
 };
 exports.convertEnumToArray = convertEnumToArray;
+/**
+ * Returns `true` when `s` can be parsed as a finite number (integer or float).
+ * Uses type coercion to reject strings with non-numeric trailing characters.
+ * @param allowNilEmpty - When true, null/empty values are treated as valid
+ */
 const isNumberString = (s, allowNilEmpty) => {
     if (allowNilEmpty && !(0, exports.isNonEmptyString)(s))
         return true;
@@ -953,6 +1136,10 @@ const isNumberString = (s, allowNilEmpty) => {
     );
 };
 exports.isNumberString = isNumberString;
+/**
+ * Returns `true` when `s` is exactly `"true"` or `"false"` (case-insensitive).
+ * @param allowNilEmpty - When true, null/empty values are treated as valid
+ */
 const isBooleanString = (s, allowNilEmpty) => {
     if (allowNilEmpty && !(0, exports.isNonEmptyString)(s))
         return true;
@@ -960,6 +1147,11 @@ const isBooleanString = (s, allowNilEmpty) => {
     return v.toLowerCase() == "true" || v.toLowerCase() == "false";
 };
 exports.isBooleanString = isBooleanString;
+/**
+ * Returns `true` when `s` represents a whole integer (no decimal point).
+ * Rejects floats like `"1.5"` even though they are numeric.
+ * @param allowNilEmpty - When true, null/empty values are treated as valid
+ */
 const isIntegerString = (s, allowNilEmpty) => {
     if (allowNilEmpty && !(0, exports.isNonEmptyString)(s))
         return true;
@@ -969,6 +1161,10 @@ const isIntegerString = (s, allowNilEmpty) => {
     return !(0, lodash_1.isNaN)(parseInt(v)) && /^-?\d+?$/.test(v);
 };
 exports.isIntegerString = isIntegerString;
+/**
+ * Returns `true` when `s` represents a floating-point number (may or may not have a decimal point).
+ * @param allowNilEmpty - When true, null/empty values are treated as valid
+ */
 const isFloatString = (s, allowNilEmpty) => {
     if (allowNilEmpty && !(0, exports.isNonEmptyString)(s))
         return true;
@@ -978,6 +1174,11 @@ const isFloatString = (s, allowNilEmpty) => {
     return !(0, lodash_1.isNaN)(parseFloat(v)) && /^-?\d+(?:[.]\d*?)?$/.test(v);
 };
 exports.isFloatString = isFloatString;
+/**
+ * Returns the timestamp (ms) of the Sunday that begins the week containing `ts`.
+ * @param ts - Unix-epoch millisecond timestamp to query
+ * @param setToFirstSecond - When true, sets the time to 00:00:00.000 of that Sunday
+ */
 const getFirstDayOfTheWeek = (ts, setToFirstSecond) => {
     const dt = new Date(ts);
     dt.setDate(dt.getDate() - dt.getDay());
@@ -987,6 +1188,11 @@ const getFirstDayOfTheWeek = (ts, setToFirstSecond) => {
     return dt.getTime();
 };
 exports.getFirstDayOfTheWeek = getFirstDayOfTheWeek;
+/**
+ * Returns the timestamp (ms) of the Saturday that ends the week containing `ts`.
+ * @param ts - Unix-epoch millisecond timestamp to query
+ * @param setToLastSecond - When true, sets the time to 23:59:59.059 of that Saturday
+ */
 const getLastDayOfTheWeek = (ts, setToLastSecond) => {
     const dt = new Date(ts);
     dt.setDate(dt.getDate() + 6 - dt.getDay());
@@ -996,6 +1202,10 @@ const getLastDayOfTheWeek = (ts, setToLastSecond) => {
     return dt.getTime();
 };
 exports.getLastDayOfTheWeek = getLastDayOfTheWeek;
+/**
+ * Removes leading and trailing newline (`\n`) characters from a string.
+ * Only newlines at the very beginning and end are stripped; internal newlines are untouched.
+ */
 const trimNewLine = (content) => {
     const chars = content.split("");
     while (chars[0] == "\n") {
@@ -1007,6 +1217,12 @@ const trimNewLine = (content) => {
     return chars.join("");
 };
 exports.trimNewLine = trimNewLine;
+/**
+ * Collapses multi-line text into a single paragraph.
+ * Leading/trailing newlines are stripped, consecutive blank lines are compressed
+ * to a single newline, then all newlines are replaced with spaces, and multiple
+ * spaces are reduced to one.
+ */
 const convertToOneParagraph = (content) => {
     return (0, exports.trimNewLine)(content)
         .replace(new RegExp(`(\n){2,}`, "g"), "\n")
@@ -1040,6 +1256,14 @@ const calculateSurcharge = (value, surcharge) => {
         : surcharge.value;
 };
 exports.calculateSurcharge = calculateSurcharge;
+/**
+ * Splits `list` into sequential sub-arrays (batches) of up to `size` items each.
+ * An optional `func` transform is applied to each element before batching.
+ * @param list - Source array to batch
+ * @param size - Maximum items per batch
+ * @param func - Optional mapping function applied to each item before batching
+ * @example generateBatchArray([1,2,3,4,5], 2) // [[1,2],[3,4],[5]]
+ */
 const generateBatchArray = (list, size, func) => {
     const result = [];
     const items = (0, lodash_1.map)(list, (c) => {
@@ -1052,6 +1276,14 @@ const generateBatchArray = (list, size, func) => {
     return result;
 };
 exports.generateBatchArray = generateBatchArray;
+/**
+ * Auto-detects and converts a string to its native type.
+ * - `"true"` / `"false"` (case-insensitive) → `boolean`
+ * - Numeric strings → `number`
+ * - Everything else → original `string`
+ * @example parseString("42") // 42
+ * @example parseString("true") // true
+ */
 const parseString = (input) => {
     // Check if the input is a boolean
     if (input.toLowerCase() === "true") {
@@ -1069,14 +1301,31 @@ const parseString = (input) => {
     return input;
 };
 exports.parseString = parseString;
+/**
+ * Returns `true` when `json` is a non-null string that parses as valid JSON without errors.
+ * Uses lodash `attempt` to avoid throwing on invalid input.
+ */
 const isGoodJSON = (json) => {
     return !(0, lodash_1.isNil)(json) && !(0, lodash_1.isError)((0, lodash_1.attempt)(JSON.parse, json));
 };
 exports.isGoodJSON = isGoodJSON;
+/**
+ * Returns a Promise that resolves after `ms` milliseconds.
+ * Use with `await` to introduce a non-blocking delay.
+ * @param ms - Delay duration in milliseconds
+ */
 const wait = (ms) => {
     return new Promise((resolve) => setTimeout(resolve, ms));
 };
 exports.wait = wait;
+/**
+ * Recursively computes the difference between two plain objects.
+ * Returns an array of change descriptors with `type` of `"added"`, `"removed"`, or `"changed"`,
+ * each containing the full dot-notation `key` and the affected value(s).
+ * @param obj1 - Base object
+ * @param obj2 - Comparison object
+ * @param path - Internal dot-notation path prefix (used in recursive calls; leave empty at call site)
+ */
 const getObjsDifference = (obj1, obj2, path = "") => {
     let diffs = [];
     const allKeys = new Set([
@@ -1111,6 +1360,12 @@ const getObjsDifference = (obj1, obj2, path = "") => {
     return diffs;
 };
 exports.getObjsDifference = getObjsDifference;
+/**
+ * Converts a string to AP-style title case.
+ * Minor words (a, an, and, as, at, but, by, for, in, nor, of, on, or, so, the, to, up, yet)
+ * are kept lowercase unless they are the first word.
+ * @example toTitle("the quick brown fox") // "The Quick Brown Fox"
+ */
 const toTitle = (str) => {
     const minorWords = new Set([
         "a",
@@ -1148,10 +1403,17 @@ const toTitle = (str) => {
     return result.join(" ");
 };
 exports.toTitle = toTitle;
+/**
+ * Generates a new RFC 4122 v4 UUID string.
+ * @returns A lowercase hyphenated UUID, e.g. `"550e8400-e29b-41d4-a716-446655440000"`
+ */
 const newGuid = () => {
     return (0, uuid_1.v4)();
 };
 exports.newGuid = newGuid;
+/**
+ * Returns the current time as a Unix timestamp in seconds (integer, floor-truncated).
+ */
 const unixTimestamp = () => {
     return Math.floor(Date.now() / 1000);
 };