@salespark/toolkit 2.0.1 → 2.1.1

package/dist/index.d.cts

@@ -181,6 +181,24 @@ declare function flattenDepth<T = unknown>(array: readonly unknown[], depth?: nu
     isStrict?: boolean;
 }): T[];
 
+/****************************************************
+ * ##: Boolean Parser
+ * Converts a value to boolean, supporting common string/number representations
+ *
+ * Notes:
+ * - Accepts "true", "yes", "1", "false", "no", "0" (case/whitespace-insensitive)
+ * - Returns default value if not recognized or on error
+ * @param {unknown} value - Input value (string | number | boolean | null | undefined)
+ * @param {Boolean} def - Default value if input cannot be parsed (default: false)
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const toBool: (value: unknown, def?: boolean) => boolean;
+/**
+ * @deprecated Use `toBool` instead.
+ */
+declare const parseToBool: (value: unknown, def?: boolean) => boolean;
+
 /**
 ****************************************************
  * ##: Object Property Picker
@@ -488,13 +506,179 @@ declare const getStringSimilarity: (s1: string, s2: string) => number;
  * 21-08-2025: Created
  ****************************************************/
 declare const addThousandsSpace: (value: number | string) => string;
+/******************************************************
+ * ##: Delay Function
+ * Creates a promise that resolves after the specified number of milliseconds
+ * @param {Number} ms - Delay in milliseconds (negative values are treated as 0)
+ * @returns {Promise<void>} Promise that resolves after the delay
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const delay: (ms: number) => Promise<void>;
+/******************************************************
+ * ##: Enforced Nil/Empty/Textual Null Check
+ * Checks if value is null/undefined/empty string or the text values "null" / "undefined" (case-insensitive)
+ * @param {unknown} value - Value to check
+ * @returns {Boolean} true if value is considered empty-like
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const isNilTextOrEmpty: (value: unknown) => boolean;
+/******************************************************
+ * ##: Modern Currency Formatter (Intl.NumberFormat)
+ * Formats currency values using modern Intl.NumberFormat API with configurable locale and currency.
+ *
+ * Provides flexible currency formatting with optional symbol display,
+ * proper decimal handling, and graceful fallback for errors.
+ * @param {number|string|null|undefined} value Currency value to format
+ * @param {boolean} withoutCurrencySymbol Hide currency symbol (show as decimal)
+ * @param {string} currency Currency code (ISO 4217, e.g., "EUR", "USD")
+ * @param {string} locale Locale string (e.g., "pt-PT", "en-US")
+ * @returns {string} Formatted currency string (e.g., "1.234,56 €" or "1.234,56")
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const formatCurrency: (value: number | string | null | undefined, withoutCurrencySymbol?: boolean, currency?: string, locale?: string) => string;
+/******************************************************
+ * ##: Parse Name into First and Last Components
+ * Extracts first and last name from a full name string.
+ *
+ * Handles edge cases like single names, empty inputs, and multi-word names.
+ * Returns first word as firstName and last word as lastName.
+ * @param {string|null|undefined} name Full name string to parse
+ * @returns {{firstName: string, lastName: string}} Object with firstName and lastName properties
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const parseName: (name: string | null | undefined) => {
+    firstName: string;
+    lastName: string;
+};
+/******************************************************
+ * ##: Currency Symbol to ISO Code Converter
+ * Converts currency symbols (€, £, $) to ISO 4217 currency codes.
+ *
+ * Maps common currency symbols to their corresponding three-letter codes.
+ * Returns "EUR" as fallback for unknown symbols.
+ * @param {string|null|undefined} symbol Currency symbol to convert (e.g., "€", "£", "$")
+ * @returns {string} ISO 4217 currency code (e.g., "EUR", "GBP", "USD")
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const symbolToCurrency: (symbol: string | null | undefined) => string;
+/******************************************************
+ * ##: ISO Currency Code to Symbol Converter
+ * Converts ISO 4217 currency codes to their corresponding symbols.
+ *
+ * Maps three-letter currency codes to common currency symbols.
+ * Returns "€" as fallback for unknown currencies.
+ * @param {string|null|undefined} currency ISO 4217 currency code (e.g., "EUR", "GBP", "USD")
+ * @returns {string} Currency symbol (e.g., "€", "£", "$")
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const currencyToSymbol: (currency: string | null | undefined) => string;
+/**
+ * @deprecated Use `isNilTextOrEmpty` instead.
+ */
+declare const isNullUndefinedOrEmptyEnforced: (value: unknown) => boolean;
 /**
  * @deprecated Use `addThousandsSpace` instead.
  */
 declare const addSpaceBetweenNumbers: (value: number | string) => string;
 
+/******************************************************
+ * ##: Portuguese Tax ID (NIF) Validator
+ * Validates a Portuguese tax identification number ("NIF").
+ *
+ * Rules / Notes:
+ * - Exactly 9 digits.
+ * - Check digit (last digit) via Mod11 weights 9..2 over first 8 digits.
+ *   sum = Σ(d[i]*w[i]); mod = sum % 11; check = (mod < 2 ? 0 : 11 - mod).
+ * - Allowed leading digits: 1,2,3,5,6,8,9.
+ * - Strips non-digit characters.
+ * - Rejects repeated digit sequences (e.g., 000000000).
+ * @param value Raw input to validate (string or number)
+ * @returns true if valid, otherwise false.
+ * History:
+ * 25-09-2025: Created as isValidPTTaxId
+ ****************************************************/
+declare function isPTTaxId(value: string | number): boolean;
+/**
+ * @deprecated Use isPTTaxId instead.
+ */
+declare const isValidPTTaxId: typeof isPTTaxId;
+
+/******************************************************
+ * ##: IBAN (International Bank Account Number) Validator
+ * Validates International Bank Account Numbers according to ISO 13616.
+ *
+ * Rules / Notes:
+ * - Country-specific format and length validation
+ * - MOD-97 checksum validation
+ * - BBAN (Basic Bank Account Number) format validation
+ * - Supports all IBAN registry countries
+ * - Strips spaces and formatting automatically
+ * @param value Raw IBAN input to validate (string)
+ * @returns true if valid IBAN, otherwise false.
+ * History:
+ * 25-09-2025: Adapted from ibantools library for SalesPark toolkit
+ ****************************************************/
+declare function isValidIBAN(value: string): boolean;
+
+/******************************************************
+ * ##: Markdown Security Checker
+ * Analyzes markdown text for potential security risks and XSS vulnerabilities.
+ *
+ * Detects dangerous HTML tags, JavaScript injection attempts, suspicious protocols,
+ * and other security threats. Provides sanitized output with detailed risk assessment.
+ * @param {string|null|undefined} markdownText Markdown content to analyze
+ * @returns {{isValid: boolean, text: string, risks: Array}} Security analysis result
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+interface SecurityRisk {
+    type: string;
+    description: string;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+}
+interface SecurityCheckResult {
+    isValid: boolean;
+    text: string;
+    risks: SecurityRisk[];
+    sanitized: boolean;
+}
+declare const checkMarkdownSecurity: (markdownText: string | null | undefined) => SecurityCheckResult;
+/******************************************************
+ * ##: HTML/Markdown Sanitizer
+ * Removes potentially dangerous HTML elements and attributes from text.
+ *
+ * More aggressive sanitization for when security is paramount.
+ * Strips all HTML tags and suspicious content.
+ * @param {string|null|undefined} text Text to sanitize
+ * @returns {string} Sanitized text with dangerous content removed
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const sanitizeMarkdown: (text: string | null | undefined) => string;
+/******************************************************
+ * ##: Security Risk Assessment
+ * Provides a security risk score and recommendations based on detected risks.
+ *
+ * Calculates risk score and provides actionable security recommendations.
+ * @param {SecurityRisk[]} risks Array of detected security risks
+ * @returns {{score: number, level: string, recommendations: string[]}} Risk assessment
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const assessSecurityRisks: (risks: SecurityRisk[]) => {
+    score: number;
+    level: "safe" | "low" | "medium" | "high" | "critical";
+    recommendations: string[];
+};
+
 /** Environment helpers (runtime-agnostic checks) */
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, basicSanitize, chunk, clamp, cleanObject, compact, debounce, deburr, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrZero, objectToString, omit, otp, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, shuffle, slugify, sortBy, stringSimilarity, throttle, toInteger, toNumber, uniq, uniqBy };
+export { type SecurityCheckResult, type SecurityRisk, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.d.ts

@@ -181,6 +181,24 @@ declare function flattenDepth<T = unknown>(array: readonly unknown[], depth?: nu
     isStrict?: boolean;
 }): T[];
 
+/****************************************************
+ * ##: Boolean Parser
+ * Converts a value to boolean, supporting common string/number representations
+ *
+ * Notes:
+ * - Accepts "true", "yes", "1", "false", "no", "0" (case/whitespace-insensitive)
+ * - Returns default value if not recognized or on error
+ * @param {unknown} value - Input value (string | number | boolean | null | undefined)
+ * @param {Boolean} def - Default value if input cannot be parsed (default: false)
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const toBool: (value: unknown, def?: boolean) => boolean;
+/**
+ * @deprecated Use `toBool` instead.
+ */
+declare const parseToBool: (value: unknown, def?: boolean) => boolean;
+
 /**
 ****************************************************
  * ##: Object Property Picker
@@ -488,13 +506,179 @@ declare const getStringSimilarity: (s1: string, s2: string) => number;
  * 21-08-2025: Created
  ****************************************************/
 declare const addThousandsSpace: (value: number | string) => string;
+/******************************************************
+ * ##: Delay Function
+ * Creates a promise that resolves after the specified number of milliseconds
+ * @param {Number} ms - Delay in milliseconds (negative values are treated as 0)
+ * @returns {Promise<void>} Promise that resolves after the delay
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const delay: (ms: number) => Promise<void>;
+/******************************************************
+ * ##: Enforced Nil/Empty/Textual Null Check
+ * Checks if value is null/undefined/empty string or the text values "null" / "undefined" (case-insensitive)
+ * @param {unknown} value - Value to check
+ * @returns {Boolean} true if value is considered empty-like
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const isNilTextOrEmpty: (value: unknown) => boolean;
+/******************************************************
+ * ##: Modern Currency Formatter (Intl.NumberFormat)
+ * Formats currency values using modern Intl.NumberFormat API with configurable locale and currency.
+ *
+ * Provides flexible currency formatting with optional symbol display,
+ * proper decimal handling, and graceful fallback for errors.
+ * @param {number|string|null|undefined} value Currency value to format
+ * @param {boolean} withoutCurrencySymbol Hide currency symbol (show as decimal)
+ * @param {string} currency Currency code (ISO 4217, e.g., "EUR", "USD")
+ * @param {string} locale Locale string (e.g., "pt-PT", "en-US")
+ * @returns {string} Formatted currency string (e.g., "1.234,56 €" or "1.234,56")
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const formatCurrency: (value: number | string | null | undefined, withoutCurrencySymbol?: boolean, currency?: string, locale?: string) => string;
+/******************************************************
+ * ##: Parse Name into First and Last Components
+ * Extracts first and last name from a full name string.
+ *
+ * Handles edge cases like single names, empty inputs, and multi-word names.
+ * Returns first word as firstName and last word as lastName.
+ * @param {string|null|undefined} name Full name string to parse
+ * @returns {{firstName: string, lastName: string}} Object with firstName and lastName properties
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const parseName: (name: string | null | undefined) => {
+    firstName: string;
+    lastName: string;
+};
+/******************************************************
+ * ##: Currency Symbol to ISO Code Converter
+ * Converts currency symbols (€, £, $) to ISO 4217 currency codes.
+ *
+ * Maps common currency symbols to their corresponding three-letter codes.
+ * Returns "EUR" as fallback for unknown symbols.
+ * @param {string|null|undefined} symbol Currency symbol to convert (e.g., "€", "£", "$")
+ * @returns {string} ISO 4217 currency code (e.g., "EUR", "GBP", "USD")
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const symbolToCurrency: (symbol: string | null | undefined) => string;
+/******************************************************
+ * ##: ISO Currency Code to Symbol Converter
+ * Converts ISO 4217 currency codes to their corresponding symbols.
+ *
+ * Maps three-letter currency codes to common currency symbols.
+ * Returns "€" as fallback for unknown currencies.
+ * @param {string|null|undefined} currency ISO 4217 currency code (e.g., "EUR", "GBP", "USD")
+ * @returns {string} Currency symbol (e.g., "€", "£", "$")
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const currencyToSymbol: (currency: string | null | undefined) => string;
+/**
+ * @deprecated Use `isNilTextOrEmpty` instead.
+ */
+declare const isNullUndefinedOrEmptyEnforced: (value: unknown) => boolean;
 /**
  * @deprecated Use `addThousandsSpace` instead.
  */
 declare const addSpaceBetweenNumbers: (value: number | string) => string;
 
+/******************************************************
+ * ##: Portuguese Tax ID (NIF) Validator
+ * Validates a Portuguese tax identification number ("NIF").
+ *
+ * Rules / Notes:
+ * - Exactly 9 digits.
+ * - Check digit (last digit) via Mod11 weights 9..2 over first 8 digits.
+ *   sum = Σ(d[i]*w[i]); mod = sum % 11; check = (mod < 2 ? 0 : 11 - mod).
+ * - Allowed leading digits: 1,2,3,5,6,8,9.
+ * - Strips non-digit characters.
+ * - Rejects repeated digit sequences (e.g., 000000000).
+ * @param value Raw input to validate (string or number)
+ * @returns true if valid, otherwise false.
+ * History:
+ * 25-09-2025: Created as isValidPTTaxId
+ ****************************************************/
+declare function isPTTaxId(value: string | number): boolean;
+/**
+ * @deprecated Use isPTTaxId instead.
+ */
+declare const isValidPTTaxId: typeof isPTTaxId;
+
+/******************************************************
+ * ##: IBAN (International Bank Account Number) Validator
+ * Validates International Bank Account Numbers according to ISO 13616.
+ *
+ * Rules / Notes:
+ * - Country-specific format and length validation
+ * - MOD-97 checksum validation
+ * - BBAN (Basic Bank Account Number) format validation
+ * - Supports all IBAN registry countries
+ * - Strips spaces and formatting automatically
+ * @param value Raw IBAN input to validate (string)
+ * @returns true if valid IBAN, otherwise false.
+ * History:
+ * 25-09-2025: Adapted from ibantools library for SalesPark toolkit
+ ****************************************************/
+declare function isValidIBAN(value: string): boolean;
+
+/******************************************************
+ * ##: Markdown Security Checker
+ * Analyzes markdown text for potential security risks and XSS vulnerabilities.
+ *
+ * Detects dangerous HTML tags, JavaScript injection attempts, suspicious protocols,
+ * and other security threats. Provides sanitized output with detailed risk assessment.
+ * @param {string|null|undefined} markdownText Markdown content to analyze
+ * @returns {{isValid: boolean, text: string, risks: Array}} Security analysis result
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+interface SecurityRisk {
+    type: string;
+    description: string;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+}
+interface SecurityCheckResult {
+    isValid: boolean;
+    text: string;
+    risks: SecurityRisk[];
+    sanitized: boolean;
+}
+declare const checkMarkdownSecurity: (markdownText: string | null | undefined) => SecurityCheckResult;
+/******************************************************
+ * ##: HTML/Markdown Sanitizer
+ * Removes potentially dangerous HTML elements and attributes from text.
+ *
+ * More aggressive sanitization for when security is paramount.
+ * Strips all HTML tags and suspicious content.
+ * @param {string|null|undefined} text Text to sanitize
+ * @returns {string} Sanitized text with dangerous content removed
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const sanitizeMarkdown: (text: string | null | undefined) => string;
+/******************************************************
+ * ##: Security Risk Assessment
+ * Provides a security risk score and recommendations based on detected risks.
+ *
+ * Calculates risk score and provides actionable security recommendations.
+ * @param {SecurityRisk[]} risks Array of detected security risks
+ * @returns {{score: number, level: string, recommendations: string[]}} Risk assessment
+ * History:
+ * 25-09-2025: Created
+ ****************************************************/
+declare const assessSecurityRisks: (risks: SecurityRisk[]) => {
+    score: number;
+    level: "safe" | "low" | "medium" | "high" | "critical";
+    recommendations: string[];
+};
+
 /** Environment helpers (runtime-agnostic checks) */
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, basicSanitize, chunk, clamp, cleanObject, compact, debounce, deburr, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrZero, objectToString, omit, otp, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, shuffle, slugify, sortBy, stringSimilarity, throttle, toInteger, toNumber, uniq, uniqBy };
+export { type SecurityCheckResult, type SecurityRisk, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };