pejay-ui 1.4.3 → 1.5.0

package/templates/utilities/formater.phoneNumber.md

@@ -0,0 +1,32 @@
+
+### Phone Number Formatter (`phone-number-formatter`)
+
+- **Description**: Parses, validates, and formats phone numbers using `libphonenumber-js`. Supports national and international numbers, country-based parsing, country calling code prefixes, and graceful handling of invalid or placeholder values.
+
+- **Exported Functions**:
+  - `setPhoneNumberFormat({ number, country, countryCode })`
+    - Formats valid phone numbers to their national format.
+    - Supports parsing using:
+      - Existing international numbers (`+1234567890`)
+      - Country calling codes (`+1`, `+91`, etc.)
+      - ISO country codes (`US`, `IN`, etc.)
+    - Returns `null` for:
+      - `null`
+      - `undefined`
+      - Empty strings
+      - Placeholder values such as `"null"`, `"undefined"`, and `"-"`
+    - Returns the original value when:
+      - The phone number is invalid
+      - Parsing fails
+    - Prioritizes parsing in the following order:
+      1. Number already contains `+`
+      2. `countryCode`
+      3. `country`
+      
+- **Features**
+  - Supports both string and numeric inputs.
+  - Handles national and international phone numbers.
+  - Supports ISO country codes and country calling codes.
+  - Safely handles null, undefined, and placeholder values.
+  - Returns original input for invalid or unparsable numbers.
+  - Formats valid numbers using `formatNational()`.

package/templates/utilities/formater.phoneNumber.ts

@@ -0,0 +1,143 @@
+import { parsePhoneNumberWithError, type CountryCode } from "libphonenumber-js";
+
+/* ------------------------------------------------
+ ? Types & Interfaces
+ ------------------------------------------------*/
+type PhoneFormatterArgs = {
+  number: string | number | null | undefined;
+  country?: CountryCode;
+  countryCode?: string; // +1, +91, etc.
+};
+
+/* ------------------------------------------------
+ ? Main function
+ @param- number: Phone number to be formatted
+ @param- country: Country code
+ @param- countryCode: Country calling code
+ @returns - Formatted phone number
+
+ *usage Type 1 (Use country code)
+
+ setPhoneNumberFormat({
+  number: "4165551234",
+  country: "US",
+  countryCode: "+1",
+ });
+
+ *useage Type 2 (Country code is provided)
+
+ setPhoneNumberFormat({
+  number: "4165551234",
+  countryCode: "+1",
+ });
+
+*useage Type 3 (only country is provided)
+
+setPhoneNumberFormat({
+  number: "4165551234",
+  country: "IN",
+});
+
+*useage Type 4 (Number already contains + ignore country code)
+
+setPhoneNumberFormat({
+  number: "+14165551234",
+  country: "IN",
+});
+
+
+
+*useage Type 5 (Number already contains + so no need to provide country code)
+
+setPhoneNumberFormat({
+  number: "+14165551234",
+});
+
+*usage Type 6 (null is provided)
+
+setPhoneNumberFormat({
+  number: null,
+});
+
+*usage Type 7 (undefined is provided)
+
+setPhoneNumberFormat({
+  number: undefined,
+});
+
+
+*usage Type 8 (placeholder value is provided)
+
+setPhoneNumberFormat({
+  number: "-",
+});
+
+*usage Type 9 (invalid number)
+
+setPhoneNumberFormat({
+  number: "abc",
+});
+
+*usage Type 10 (unformatted number)
+
+setPhoneNumberFormat({
+  number: "1234",
+});
+
+------------------------------------------------*/
+export function setPhoneNumberFormat({
+  number,
+  country,
+  countryCode,
+}: PhoneFormatterArgs): string | null {
+  // Handle nullish values
+  if (number == null) return null;
+  const strNum = String(number).trim();
+
+  // Handle common placeholder values
+  if (!strNum || ["null", "undefined", "-"].includes(strNum.toLowerCase())) {
+    return null;
+  }
+
+  try {
+    let phoneInput = strNum;
+
+    /**
+     * NOTE : Priority:
+     * 1. Number already contains '+'
+     * 2. countryCode
+     * 3. country
+     */
+
+    if (!phoneInput.startsWith("+") && countryCode) {
+      phoneInput = `${countryCode}${phoneInput}`;
+    }
+
+    const phone = phoneInput.startsWith("+")
+      ? parsePhoneNumberWithError(phoneInput)
+      : parsePhoneNumberWithError(phoneInput, country);
+
+    if (!phone.isValid()) {
+      return strNum;
+    }
+
+    return phone.formatNational();
+  } catch {
+    return strNum;
+  }
+}
+
+/* 
+
+*what number can handel as input 
+
+1. null/undefined      -> null
+2. "", "null", "-"     -> null
+3. Number starts "+"   -> parse as international
+4. countryCode         -> prepend and parse
+5. country             -> parse as national
+6. Valid number        -> formatNational()
+7. Invalid number      -> return original value
+8. Parse error         -> return original value
+
+*/

package/templates/utilities/sanitize.md

@@ -0,0 +1,23 @@
+### Sanitize Data (`sanitize-fn`)
+
+- **Description**: Recursively trims string values, nullifies empty strings, and checks for empty payloads in form data.
+
+- **Exported Functions**:
+  - `sanitizeFormData({ data, skip, nullifyEmptyStrings })`
+    - Sanitizes an entire object and returns:
+      ```ts
+      {
+        isEmpty: boolean;
+        data: T;
+      }
+      ```
+    - Supports nested field exclusion using dot notation (e.g. `"user.email"`).
+    - Optionally preserves empty strings by setting `nullifyEmptyStrings` to `false`.
+
+- **Features**
+  - Trims leading and trailing whitespace from strings.
+  - Converts empty strings to `null` (configurable).
+  - Supports nested objects and arrays.
+  - Supports skipping specific fields using dot notation.
+  - Preserves `Date` and `File` instances.
+  - Returns an `isEmpty` flag for quick form validation.

package/templates/utilities/sanitize.ts

@@ -0,0 +1,148 @@
+/* ------------------------------------------------
+ ? Types & Interfaces
+ ------------------------------------------------*/
+type SanitizeFormDataOptions<T> = {
+  data: T;
+  skip?: string[];
+  nullifyEmptyStrings?: boolean;
+};
+
+type SanitizeFormDataResult<T> = {
+  isEmpty: boolean;
+  data: T;
+};
+
+/* ------------------------------------------------
+ ? Main function
+ @param - data: Object to be sanitized
+ @param - skip: Array of keys to skip
+ @param - nullifyEmptyStrings: Whether to nullify empty strings
+ @returns - Sanitized object
+
+ *usage Type 1
+
+ const {isEmpty,data:sanitizedData} = sanitizeFormData({data});
+
+ if(isEmpty){
+  return;
+ }
+
+ *usage Type 2 
+ const {isEmpty,data:sanitizedData} = sanitizeFormData({data, skip:["password","user.email",]});
+ 
+ if(isEmpty){
+  return;
+ }
+
+ # NOTE : skip contains dot notation for nested objects and key names whose value will skip from sanitizing
+
+ *usage Type 3
+ const {isEmpty,data:sanitizedData} = sanitizeFormData({data, skip:["password","user.email",], nullifyEmptyStrings:false});
+
+ if(isEmpty){
+  return;
+ }
+
+ 
+ ------------------------------------------------*/
+export const sanitizeFormData = <T>({
+  data,
+  skip = [],
+  nullifyEmptyStrings = true,
+}: SanitizeFormDataOptions<T>): SanitizeFormDataResult<T> => {
+  const skipSet = new Set(skip);
+  const sanitizedData = sanitize(data, "", skipSet, nullifyEmptyStrings) as T;
+  return {
+    isEmpty: isEmptyValue(sanitizedData),
+    data: sanitizedData,
+  };
+};
+
+/* ------------------------------------------------
+ # ANCHOR : Helper Functions
+ ------------------------------------------------*/
+
+/* ------------------------------------------------
+ ? Recursive Function
+ @param - value: Value to be sanitized
+ @param - path: Path of the value
+ @param - skipSet: Set of keys to skip
+ @param - nullifyEmptyStrings: Whether to nullify empty strings
+ @returns - Sanitized value
+ ------------------------------------------------*/
+export function sanitize(
+  value: unknown,
+  path = "",
+  skipSet: Set<string>,
+  nullifyEmptyStrings: boolean,
+): unknown {
+  // Strings
+  if (typeof value === "string") {
+    if (skipSet.has(path)) {
+      return value;
+    }
+
+    const trimmed = value.trim();
+
+    return nullifyEmptyStrings && trimmed === "" ? null : trimmed;
+  }
+
+  // Arrays
+  if (Array.isArray(value)) {
+    return value.map((item, index) =>
+      sanitize(item, `${path}[${index}]`, skipSet, nullifyEmptyStrings),
+    );
+  }
+
+  // Plain Objects
+  if (
+    value &&
+    typeof value === "object" &&
+    !(value instanceof Date) &&
+    !(value instanceof File)
+  ) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, val]) => [
+        key,
+        sanitize(
+          val,
+          path ? `${path}.${key}` : key,
+          skipSet,
+          nullifyEmptyStrings,
+        ),
+      ]),
+    );
+  }
+
+  return value;
+}
+
+/* ------------------------------------------------
+ ? Check if value is empty
+ @param - value: Value to be checked
+ @returns - boolean
+ ------------------------------------------------*/
+export function isEmptyValue(value: unknown): boolean {
+  if (value === null) return true;
+
+  if (typeof value === "string") {
+    return value.trim() === "";
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0 || value.every(isEmptyValue);
+  }
+
+  if (
+    value &&
+    typeof value === "object" &&
+    !(value instanceof Date) &&
+    !(value instanceof File)
+  ) {
+    const values = Object.values(value);
+
+    return values.length === 0 || values.every(isEmptyValue);
+  }
+
+  return false;
+}