@salespark/toolkit 2.1.11 → 2.1.13

package/dist/index.d.cts

@@ -437,7 +437,7 @@ declare const toInteger: typeof safeParseInt;
  * Handles commas as decimal/thousands separators. Returns 0 for null/undefined/empty string or invalid parsing.
  * Examples: safeParseFloat("123.45") -> 123.45, safeParseFloat("123,45") -> 123.45, safeParseFloat("1,234.56") -> 1234.56, safeParseFloat("abc", 2) -> 0, safeParseFloat(42) -> 42
  * @param {unknown} value - Value to convert
- * @param {number} decimals - Number of decimal places
+ * @param {number} decimals - Number of decimal places (default 6)
  * History:
  * 21-08-2025: Created
  * 29-10-2025: Renamed from toNumber to safeParseFloat
@@ -828,8 +828,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

@@ -437,7 +437,7 @@ declare const toInteger: typeof safeParseInt;
  * Handles commas as decimal/thousands separators. Returns 0 for null/undefined/empty string or invalid parsing.
  * Examples: safeParseFloat("123.45") -> 123.45, safeParseFloat("123,45") -> 123.45, safeParseFloat("1,234.56") -> 1234.56, safeParseFloat("abc", 2) -> 0, safeParseFloat(42) -> 42
  * @param {unknown} value - Value to convert
- * @param {number} decimals - Number of decimal places
+ * @param {number} decimals - Number of decimal places (default 6)
  * History:
  * 21-08-2025: Created
  * 29-10-2025: Renamed from toNumber to safeParseFloat
@@ -828,8 +828,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

@@ -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