@salespark/toolkit 2.1.11 → 2.1.13

package/README.md

@@ -29,6 +29,7 @@ npm i @salespark/toolkit
 - **String utilities**: slugify, template fill, deburr, sanitize, capitalize words/sentences.
 - **Number utilities**: clamp, round, safe arithmetic/comparisons, safe parse (locale-aware), random digits, etc.
 - **Function utilities**: debounce, throttle, safeJSONParse, formatCurrency, parseName, currency conversions, etc.
+- **Defer utilities**: post-return microtask scheduling, non-critical timers, after-response hooks.
 - **Boolean utilities**: safe boolean conversion with common representations
 - **Validation utilities**: IBAN validator (ISO 13616), Portuguese tax ID validator
 - **Security utilities**: Markdown XSS protection, content sanitization, risk assessment
@@ -704,6 +705,43 @@ currencyToSymbol("UNKNOWN");
 // Result: "€" (fallback)
 ```
 
+### 🕒 Defer Utilities
+
+**`deferPostReturn(fn: () => void | Promise<void>): void`** — Runs a function right after the current call stack completes (microtask), without blocking the caller.
+
+```javascript
+const order = [];
+order.push("a");
+deferPostReturn(() => order.push("b"));
+order.push("c");
+// After the current stack finishes (microtask): order = ["a", "c", "b"]
+```
+
+**`deferNonCritical(fn: () => void | Promise<void>): void`** — Schedules a function as late as possible (low priority) for non-critical work.
+
+```javascript
+deferNonCritical(() => {
+  // logs, metrics, cleanup — runs later without competing with main work
+});
+```
+
+**`deferAfterResponse(res: { once: (event: "finish" | "close", listener: (...args: any[]) => void) => void; writableEnded?: boolean }, fn: () => void | Promise<void>): void`** — Runs a function after the HTTP response is finished (sent to the client), scheduled soon (microtask).
+
+```javascript
+// Example with a response-like object
+deferAfterResponse(res, () => {
+  // post-response tasks — lightweight, run shortly after sending
+});
+```
+
+**`deferAfterResponseNonCritical(res: { once: (event: "finish" | "close", listener: (...args: any[]) => void) => void; writableEnded?: boolean }, fn: () => void | Promise<void>): void`** — Runs a function after the HTTP response is finished, scheduled as low priority (as late as possible).
+
+```javascript
+deferAfterResponseNonCritical(res, () => {
+  // non-critical post-response work — scheduled with low priority
+});
+```
+
 ### 🔒 Security Utilities
 
 **`checkMarkdownSecurity(text: string | null | undefined): SecurityCheckResult`** — Comprehensive markdown security validation with XSS protection, threat detection, and automatic sanitization.
@@ -908,5 +946,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 12_  
-_Last update: 21-12-2025_
+_Document version: 13_  
+_Last update: 09-01-2026_

package/dist/index.cjs

@@ -1745,6 +1745,90 @@ 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;
@@ -1765,6 +1849,10 @@ exports.compact = compact;
 exports.currencyToSymbol = currencyToSymbol;
 exports.debounce = debounce;
 exports.deburr = deburr;
+exports.deferAfterResponse = deferAfterResponse;
+exports.deferAfterResponseNonCritical = deferAfterResponseNonCritical;
+exports.deferNonCritical = deferNonCritical;
+exports.deferPostReturn = deferPostReturn;
 exports.delay = delay;
 exports.difference = difference;
 exports.fill = fill;