@salespark/toolkit 2.1.12 → 2.1.14

package/dist/index.d.cts

@@ -624,14 +624,16 @@ declare const isNullOrUndefinedOrNaN: (value: unknown) => boolean;
  * @param {Number} bytes - Number of bytes to format
  * @param {Boolean} si - True for metric (SI, base 1000), false for binary (IEC, base 1024)
  * @param {Number} dp - Decimal places
+ * @param {Boolean} noSpace - If true, omits space between number and unit
  * History:
  * 21-08-2025: Created
+ * 15-01-2026: Returns "Bytes" instead of "B" for values < threshold for clarity and added noSpace option
  ****************************************************/
-declare const formatBytes: (bytes: number, si?: boolean, dp?: number) => string;
+declare const formatBytes: (bytes: number, si?: boolean, dp?: number, noSpace?: boolean) => string;
 /**
  * @deprecated Use `formatBytes` instead.
  */
-declare const humanFileSize: (bytes: number, si?: boolean, dp?: number) => string;
+declare const humanFileSize: (bytes: number, si?: boolean, dp?: number, noSpace?: boolean) => string;
 /******************************************************
  * ##: String Similarity
  * Returns the similarity between two strings (0..1)
@@ -828,8 +830,69 @@ declare const assessSecurityRisks: (risks: SecurityRisk[]) => {
     recommendations: string[];
 };
 
+type DeferFn = () => void | Promise<void>;
+/******************************************************************
+ * ##: Defer work to run right after return using a microtask
+ * Schedules work after the current call stack, using queueMicrotask or
+ * Promise.then, and swallows sync/async errors to avoid impacting callers.
+ *
+ * TL;DR: Runs post-return work ASAP without blocking the caller.
+ * Best for small but important tasks that must run soon.
+ * @param {DeferFn} fn - Function to execute after the current stack completes
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2026: Created
+ ******************************************************************/
+declare const deferPostReturn: (fn: DeferFn) => void;
+/******************************************************************
+ * ##: Defer non-critical work with low priority scheduling
+ * Schedules work after more urgent tasks, using setImmediate when available
+ * (or setTimeout), and swallows sync/async errors to keep execution safe.
+ *
+ * TL;DR: Runs low-priority work as late as possible.
+ * Ideal for logs, metrics, and cleanup that must not compete with requests.
+ * @param {DeferFn} fn - Function to execute with low priority scheduling
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2026: Created
+ ******************************************************************/
+declare const deferNonCritical: (fn: DeferFn) => void;
+type HttpResponseLike = {
+    once: (event: "finish" | "close", listener: (...args: any[]) => void) => void;
+    writableEnded?: boolean;
+};
+/******************************************************************
+ * ##: Defer work until after the HTTP response finishes
+ * Runs work only after the response is completed (finish/close), ensures it
+ * executes once, and schedules via microtask to avoid impacting response time.
+ *
+ * TL;DR: Runs work after sending the response, exactly once.
+ * Use for post-response tasks like logging, metrics, or async side effects.
+ * @param {HttpResponseLike} res - Response-like object that emits finish/close events
+ * @param {DeferFn} fn - Function to execute after the response has completed
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2026: Created
+ ******************************************************************/
+declare const deferAfterResponse: (res: HttpResponseLike, fn: DeferFn) => void;
+/******************************************************************
+ * ##: Defer low-priority work until after the HTTP response finishes
+ * Runs work only after the response is completed (finish/close), ensures it
+ * executes once, and schedules with low priority to avoid competing with traffic.
+ *
+ * TL;DR: Runs low-priority work after sending the response, exactly once.
+ * Best for non-urgent metrics, logs, and cleanup after request completion.
+ * @param {HttpResponseLike} res - Response-like object that emits finish/close events
+ * @param {DeferFn} fn - Function to execute after the response has completed
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2025: Created
+ * 09-01-2025: Fixed duplicate execution bug (finish + close both firing)
+ ******************************************************************/
+declare const deferAfterResponseNonCritical: (res: HttpResponseLike, fn: DeferFn) => void;
+
 /** Environment helpers (runtime-agnostic checks) */
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type DeferFn, type HttpResponseLike, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.d.ts

@@ -624,14 +624,16 @@ declare const isNullOrUndefinedOrNaN: (value: unknown) => boolean;
  * @param {Number} bytes - Number of bytes to format
  * @param {Boolean} si - True for metric (SI, base 1000), false for binary (IEC, base 1024)
  * @param {Number} dp - Decimal places
+ * @param {Boolean} noSpace - If true, omits space between number and unit
  * History:
  * 21-08-2025: Created
+ * 15-01-2026: Returns "Bytes" instead of "B" for values < threshold for clarity and added noSpace option
  ****************************************************/
-declare const formatBytes: (bytes: number, si?: boolean, dp?: number) => string;
+declare const formatBytes: (bytes: number, si?: boolean, dp?: number, noSpace?: boolean) => string;
 /**
  * @deprecated Use `formatBytes` instead.
  */
-declare const humanFileSize: (bytes: number, si?: boolean, dp?: number) => string;
+declare const humanFileSize: (bytes: number, si?: boolean, dp?: number, noSpace?: boolean) => string;
 /******************************************************
  * ##: String Similarity
  * Returns the similarity between two strings (0..1)
@@ -828,8 +830,69 @@ declare const assessSecurityRisks: (risks: SecurityRisk[]) => {
     recommendations: string[];
 };
 
+type DeferFn = () => void | Promise<void>;
+/******************************************************************
+ * ##: Defer work to run right after return using a microtask
+ * Schedules work after the current call stack, using queueMicrotask or
+ * Promise.then, and swallows sync/async errors to avoid impacting callers.
+ *
+ * TL;DR: Runs post-return work ASAP without blocking the caller.
+ * Best for small but important tasks that must run soon.
+ * @param {DeferFn} fn - Function to execute after the current stack completes
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2026: Created
+ ******************************************************************/
+declare const deferPostReturn: (fn: DeferFn) => void;
+/******************************************************************
+ * ##: Defer non-critical work with low priority scheduling
+ * Schedules work after more urgent tasks, using setImmediate when available
+ * (or setTimeout), and swallows sync/async errors to keep execution safe.
+ *
+ * TL;DR: Runs low-priority work as late as possible.
+ * Ideal for logs, metrics, and cleanup that must not compete with requests.
+ * @param {DeferFn} fn - Function to execute with low priority scheduling
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2026: Created
+ ******************************************************************/
+declare const deferNonCritical: (fn: DeferFn) => void;
+type HttpResponseLike = {
+    once: (event: "finish" | "close", listener: (...args: any[]) => void) => void;
+    writableEnded?: boolean;
+};
+/******************************************************************
+ * ##: Defer work until after the HTTP response finishes
+ * Runs work only after the response is completed (finish/close), ensures it
+ * executes once, and schedules via microtask to avoid impacting response time.
+ *
+ * TL;DR: Runs work after sending the response, exactly once.
+ * Use for post-response tasks like logging, metrics, or async side effects.
+ * @param {HttpResponseLike} res - Response-like object that emits finish/close events
+ * @param {DeferFn} fn - Function to execute after the response has completed
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2026: Created
+ ******************************************************************/
+declare const deferAfterResponse: (res: HttpResponseLike, fn: DeferFn) => void;
+/******************************************************************
+ * ##: Defer low-priority work until after the HTTP response finishes
+ * Runs work only after the response is completed (finish/close), ensures it
+ * executes once, and schedules with low priority to avoid competing with traffic.
+ *
+ * TL;DR: Runs low-priority work after sending the response, exactly once.
+ * Best for non-urgent metrics, logs, and cleanup after request completion.
+ * @param {HttpResponseLike} res - Response-like object that emits finish/close events
+ * @param {DeferFn} fn - Function to execute after the response has completed
+ * @returns {void} - Does not return a value
+ * History:
+ * 09-01-2025: Created
+ * 09-01-2025: Fixed duplicate execution bug (finish + close both firing)
+ ******************************************************************/
+declare const deferAfterResponseNonCritical: (res: HttpResponseLike, fn: DeferFn) => void;
+
 /** Environment helpers (runtime-agnostic checks) */
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type DeferFn, type HttpResponseLike, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.js

@@ -551,11 +551,11 @@ var isNullOrUndefinedInArray = hasNilOrEmpty;
 var isNullOrUndefinedEmptyOrZero = isNilEmptyOrZeroLen;
 var isNullUndefinedOrZero = isNilOrZeroLen;
 var isNullOrUndefinedOrNaN = isNilOrNaN;
-var formatBytes = (bytes, si = false, dp = 1) => {
+var formatBytes = (bytes, si = false, dp = 1, noSpace = false) => {
   if (!Number.isFinite(bytes)) return "NaN";
   const thresh = si ? 1e3 : 1024;
   const abs = Math.abs(bytes);
-  if (abs < thresh) return `${bytes} B`;
+  if (abs < thresh) return `${bytes} Bytes`;
   const units = si ? ["kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"] : ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"];
   let u = -1;
   const r = 10 ** dp;
@@ -564,7 +564,7 @@ var formatBytes = (bytes, si = false, dp = 1) => {
     value /= thresh;
     ++u;
   } while (Math.round(Math.abs(value) * r) / r >= thresh && u < units.length - 1);
-  return `${value.toFixed(dp)} ${units[u]}`;
+  return `${value.toFixed(dp)}${noSpace ? "" : " "}${units[u]}`;
 };
 var humanFileSize = formatBytes;
 var levenshtein = (a, b) => {
@@ -1743,10 +1743,94 @@ var assessSecurityRisks = (risks) => {
   return { score, level, recommendations };
 };
 
+// src/utils/defer.ts
+var swallow = (p) => p.catch(() => {
+});
+var deferPostReturn = (fn) => {
+  if (typeof fn !== "function") return;
+  const run = () => {
+    try {
+      const result = fn();
+      swallow(Promise.resolve(result));
+    } catch {
+    }
+  };
+  if (typeof queueMicrotask === "function") {
+    queueMicrotask(run);
+  } else {
+    Promise.resolve().then(run);
+  }
+};
+var deferNonCritical = (fn) => {
+  if (typeof fn !== "function") return;
+  const run = () => {
+    try {
+      const result = fn();
+      swallow(Promise.resolve(result));
+    } catch {
+    }
+  };
+  if (typeof setImmediate === "function") {
+    setImmediate(run);
+  } else {
+    setTimeout(run, 0);
+  }
+};
+var deferAfterResponse = (res, fn) => {
+  if (typeof fn !== "function") return;
+  if (res?.writableEnded === true) {
+    deferPostReturn(fn);
+    return;
+  }
+  if (!res || typeof res.once !== "function") {
+    deferPostReturn(fn);
+    return;
+  }
+  let executed = false;
+  const executeOnce = () => {
+    if (executed) return;
+    executed = true;
+    deferPostReturn(fn);
+  };
+  try {
+    res.once("finish", executeOnce);
+    res.once("close", executeOnce);
+  } catch {
+    if (!executed) {
+      deferPostReturn(fn);
+    }
+  }
+};
+var deferAfterResponseNonCritical = (res, fn) => {
+  if (typeof fn !== "function") return;
+  if (res?.writableEnded === true) {
+    deferNonCritical(fn);
+    return;
+  }
+  if (!res || typeof res.once !== "function") {
+    deferNonCritical(fn);
+    return;
+  }
+  let executed = false;
+  const executeOnce = () => {
+    if (executed) return;
+    executed = true;
+    deferNonCritical(fn);
+  };
+  try {
+    res.once("finish", executeOnce);
+    res.once("close", executeOnce);
+  } catch {
+    if (!executed) {
+      deferNonCritical(fn);
+    }
+  }
+};
+
 // src/index.ts
 var isBrowser = typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
 var isNode = typeof process !== "undefined" && !!process.versions?.node;
 
-export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map