@salespark/toolkit 2.1.13 → 2.1.15

package/README.md

@@ -32,7 +32,7 @@ npm i @salespark/toolkit
 - **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
+- **Security utilities**: Markdown XSS protection, content sanitization, risk assessment, obfuscation helpers
 - **Environment detection**: `isBrowser`, `isNode` runtime checks
 
 ---
@@ -135,7 +135,7 @@ uniqBy(
     { id: 2, name: "Jane" },
     { id: 1, name: "John" },
   ],
-  (x) => x.id
+  (x) => x.id,
 );
 // Result: [{id: 1, name: 'John'}, {id: 2, name: 'Jane'}]
 ```
@@ -177,7 +177,7 @@ groupBy(
     { type: "fruit", name: "banana" },
     { type: "veggie", name: "carrot" },
   ],
-  "type"
+  "type",
 );
 // Result: {fruit: [{type: 'fruit', name: 'apple'}, {type: 'fruit', name: 'banana'}], veggie: [{type: 'veggie', name: 'carrot'}]}
 ```
@@ -218,7 +218,7 @@ pluck(
     { name: "John", age: 30 },
     { name: "Jane", age: 25 },
   ],
-  "name"
+  "name",
 );
 // Result: ['John', 'Jane']
 ```
@@ -290,7 +290,7 @@ cleanObject(
     note: "",
     tags: ["", "ok"],
   },
-  true
+  true,
 );
 // Result: {name: 'John', tags: ['ok']}
 ```
@@ -584,14 +584,17 @@ isNilOrNaN("abc");
 // Result: true (coerced to NaN)
 ```
 
-**`formatBytes(bytes: number, si?: boolean, dp?: number): string`** — Formats bytes as human-readable text.
+**`formatBytes(bytes: number, si?: boolean, dp?: number, noSpace?: boolean): string`** — Formats bytes as human-readable text.
 
 ```javascript
+formatBytes(999, true);
+// Result: "999 Bytes"
+
 formatBytes(1024);
 // Result: "1.0 KiB"
 
-formatBytes(1000, true);
-// Result: "1.0 kB"
+formatBytes(1000, true, 1, true);
+// Result: "1.0kB"
 ```
 
 **`stringSimilarity(s1: string, s2: string): number`** — Returns the similarity between two strings (0..1).
@@ -648,6 +651,26 @@ formatCurrency(null);
 // Result: "0,00 €"
 ```
 
+**`formatCurrencyPro(value: number | string | null | undefined, options?: { withoutCurrencySymbol?: boolean; currency?: string; locale?: string; redact?: boolean; redactChar?: string }): string`** — Same as `formatCurrency`, but uses a single options object and supports redaction.
+
+```javascript
+// Same defaults as formatCurrency
+formatCurrencyPro(1234.56);
+// Result: "1234,56 €"
+
+// Options object
+formatCurrencyPro(1234.56, { currency: "USD", locale: "en-US" });
+// Result: "$1,234.56"
+
+// Redacted output (mask digits)
+formatCurrencyPro(1234.56, { redact: true });
+// Result: "****,** €"
+
+// Custom redaction character
+formatCurrencyPro(1234.56, { redact: true, redactChar: "•" });
+// Result: "••••,•• €"
+```
+
 **`parseName(name: string | null | undefined): {firstName: string, lastName: string}`** — Extracts first and last name from a full name string. Handles single names, empty inputs, and multi-word names intelligently.
 
 ```javascript
@@ -764,7 +787,7 @@ checkMarkdownSecurity('<script>alert("xss")</script>');
 
 // Content with multiple threats
 checkMarkdownSecurity(
-  '<iframe src="evil.com"></iframe><div onclick="bad()">test</div>'
+  '<iframe src="evil.com"></iframe><div onclick="bad()">test</div>',
 );
 // Result: Multiple risks detected, sorted by severity
 ```
@@ -813,6 +836,30 @@ assessSecurityRisks([]);
 // Result: { score: 0, level: "safe", recommendations: ["Content appears safe to use"] }
 ```
 
+**`scrambleString(value: string, secret: string): string`** — Scrambles a string using a repeating secret (XOR) and Base64. Reversible obfuscation only (not crypto).
+
+```javascript
+const scrambled = scrambleString("Hello", "secret");
+// Result: "..." (base64)
+
+const original = descrambleString(scrambled, "secret");
+// Result: "Hello"
+```
+
+**`descrambleString(value: string, secret: string): string`** — Reverses `scrambleString` using the same secret.
+
+**`encodeObject(input: object, secret: string): string`** — JSON-stringifies an object, Base64-encodes it, and scrambles the result (obfuscation only).
+
+```javascript
+const encoded = encodeObject({ id: 1, name: "Ana" }, "secret");
+// Result: "..." (base64)
+
+const decoded = decodeObject(encoded, "secret");
+// Result: { id: 1, name: "Ana" }
+```
+
+**`decodeObject(encoded: string, secret: string): object`** — Reverses `encodeObject` using the same secret.
+
 ### ✅ Validation Utilities
 
 **`isPTTaxId(value: string | number): boolean`** — Validates Portuguese Tax ID (NIF) with MOD-11 algorithm and format checking.

package/dist/index.cjs

@@ -553,11 +553,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;
@@ -566,7 +566,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 === true ? "" : " "}${units[u]}`;
 };
 var humanFileSize = formatBytes;
 var levenshtein = (a, b) => {
@@ -658,6 +658,35 @@ var formatCurrency = (value, withoutCurrencySymbol = false, currency = "EUR", lo
     return withoutCurrencySymbol ? formatted : `${formatted} \u20AC`;
   }
 };
+var formatCurrencyPro = (value, options = {}) => {
+  const resolvedWithoutSymbol = options.withoutCurrencySymbol === true;
+  const resolvedCurrency = options.currency ?? "EUR";
+  const resolvedLocale = options.locale ?? "pt-PT";
+  const redact = options.redact === true;
+  const redactChar = options.redactChar ? options.redactChar : "*";
+  try {
+    const numValue = value === void 0 || value === null || value === "" ? 0 : Number(value);
+    if (isNaN(numValue) || !isFinite(numValue)) {
+      const fallback = resolvedWithoutSymbol ? "0,00" : "0,00 \u20AC";
+      return redact ? fallback.replace(/\d/g, redactChar) : fallback;
+    }
+    const intlOptions = {
+      style: resolvedWithoutSymbol ? "decimal" : "currency",
+      currency: resolvedCurrency,
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2
+    };
+    const formatted = new Intl.NumberFormat(resolvedLocale, intlOptions).format(
+      numValue
+    );
+    return redact ? formatted.replace(/\d/g, redactChar) : formatted;
+  } catch (error) {
+    const numValue = Number(value) || 0;
+    const formatted = numValue.toFixed(2).replace(".", ",");
+    const fallback = resolvedWithoutSymbol ? formatted : `${formatted} \u20AC`;
+    return redact ? fallback.replace(/\d/g, redactChar) : fallback;
+  }
+};
 var parseName = (name) => {
   try {
     if (name === void 0 || name === null || name === "") {
@@ -1745,6 +1774,109 @@ var assessSecurityRisks = (risks) => {
   return { score, level, recommendations };
 };
 
+// src/utils/scramble.ts
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.from === "function";
+var base64EncodeBinary = (binary) => {
+  if (hasBuffer) {
+    return Buffer.from(binary, "binary").toString("base64");
+  }
+  if (typeof btoa === "function") {
+    return btoa(binary);
+  }
+  throw new Error("Base64 encoder not available");
+};
+var base64DecodeToBinary = (base64) => {
+  if (hasBuffer) {
+    return Buffer.from(base64, "base64").toString("binary");
+  }
+  if (typeof atob === "function") {
+    return atob(base64);
+  }
+  throw new Error("Base64 decoder not available");
+};
+var utf8ToBinary = (value) => {
+  if (hasBuffer) {
+    return Buffer.from(value, "utf8").toString("binary");
+  }
+  if (typeof TextEncoder !== "undefined") {
+    const bytes = new TextEncoder().encode(value);
+    let binary = "";
+    for (const b of bytes) {
+      binary += String.fromCharCode(b);
+    }
+    return binary;
+  }
+  return value;
+};
+var binaryToUtf8 = (binary) => {
+  if (hasBuffer) {
+    return Buffer.from(binary, "binary").toString("utf8");
+  }
+  if (typeof TextDecoder !== "undefined") {
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i) & 255;
+    }
+    return new TextDecoder().decode(bytes);
+  }
+  return binary;
+};
+var toBase64 = (value) => base64EncodeBinary(utf8ToBinary(value));
+var fromBase64 = (value) => binaryToUtf8(base64DecodeToBinary(value));
+var scrambleString = (value, secret) => {
+  if (typeof value !== "string") {
+    throw new TypeError("Value must be a string");
+  }
+  if (!secret || typeof secret !== "string") {
+    throw new TypeError("Secret must be a non-empty string");
+  }
+  let result = "";
+  for (let i = 0; i < value.length; i++) {
+    const charCode = value.charCodeAt(i) & 255;
+    const keyCode = secret.charCodeAt(i % secret.length) & 255;
+    result += String.fromCharCode(charCode ^ keyCode);
+  }
+  return base64EncodeBinary(result);
+};
+var descrambleString = (value, secret) => {
+  if (typeof value !== "string") {
+    throw new TypeError("Value must be a string");
+  }
+  if (!secret || typeof secret !== "string") {
+    throw new TypeError("Secret must be a non-empty string");
+  }
+  const decoded = base64DecodeToBinary(value);
+  let result = "";
+  for (let i = 0; i < decoded.length; i++) {
+    const charCode = decoded.charCodeAt(i) & 255;
+    const keyCode = secret.charCodeAt(i % secret.length) & 255;
+    result += String.fromCharCode(charCode ^ keyCode);
+  }
+  return result;
+};
+var encodeObject = (input, secret) => {
+  if (!input || typeof input !== "object") {
+    throw new TypeError("Input must be an object");
+  }
+  if (!secret || typeof secret !== "string") {
+    throw new TypeError("Secret must be a non-empty string");
+  }
+  const jsonString = JSON.stringify(input);
+  const base64 = toBase64(jsonString);
+  return scrambleString(base64, secret);
+};
+var decodeObject = (encoded, secret) => {
+  if (typeof encoded !== "string") {
+    throw new TypeError("Encoded value must be a string");
+  }
+  if (!secret || typeof secret !== "string") {
+    throw new TypeError("Secret must be a non-empty string");
+  }
+  const descrambled = descrambleString(encoded, secret);
+  const jsonString = fromBase64(descrambled);
+  return JSON.parse(jsonString);
+};
+
 // src/utils/defer.ts
 var swallow = (p) => p.catch(() => {
 });
@@ -1849,12 +1981,15 @@ exports.compact = compact;
 exports.currencyToSymbol = currencyToSymbol;
 exports.debounce = debounce;
 exports.deburr = deburr;
+exports.decodeObject = decodeObject;
 exports.deferAfterResponse = deferAfterResponse;
 exports.deferAfterResponseNonCritical = deferAfterResponseNonCritical;
 exports.deferNonCritical = deferNonCritical;
 exports.deferPostReturn = deferPostReturn;
 exports.delay = delay;
+exports.descrambleString = descrambleString;
 exports.difference = difference;
+exports.encodeObject = encodeObject;
 exports.fill = fill;
 exports.flatten = flatten;
 exports.flattenDepth = flattenDepth;
@@ -1862,6 +1997,7 @@ exports.flattenDepthBase = flattenDepthBase;
 exports.flattenOnce = flattenOnce;
 exports.formatBytes = formatBytes;
 exports.formatCurrency = formatCurrency;
+exports.formatCurrencyPro = formatCurrencyPro;
 exports.formatDecimalNumber = formatDecimalNumber;
 exports.getStringSimilarity = getStringSimilarity;
 exports.groupBy = groupBy;
@@ -1913,6 +2049,7 @@ exports.safeParseInt = safeParseInt;
 exports.safeSubtract = safeSubtract;
 exports.sanitize = sanitize;
 exports.sanitizeMarkdown = sanitizeMarkdown;
+exports.scrambleString = scrambleString;
 exports.sentenceCase = sentenceCase;
 exports.shuffle = shuffle;
 exports.slugify = slugify;