@ibiliaze/stringman 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -1,8 +1,129 @@
+/**
+ * Clean up extra whitespace in a string.
+ *
+ * - Collapses multiple consecutive whitespace characters (spaces, tabs, newlines)
+ *   into a single space.
+ * - Trims leading and trailing whitespace.
+ *
+ * @param stringData - The input string to clean
+ * @returns The cleaned string with normalized spacing
+ *
+ * Example:
+ *   superTrim("   Hello    World   ");
+ *   // → "Hello World"
+ *
+ *   superTrim("Line1\n\nLine2");
+ *   // → "Line1 Line2"
+ */
 export declare const superTrim: (stringData: string) => string;
+/**
+ * Remove extra whitespace from a string.
+ *
+ * - Collapses multiple consecutive whitespace characters into a single empty string (removes them completely).
+ * - Useful for cleaning up text where multiple spaces, tabs, or line breaks appear.
+ *
+ * @param stringData - The input string to clean
+ * @returns The string with extra whitespace removed
+ *
+ * Example:
+ *   megaTrim("Hello    World");   // → "HelloWorld"
+ *   megaTrim("Line1\n\n\nLine2"); // → "Line1Line2"
+ */
 export declare const megaTrim: (stringData: string) => string;
+/**
+ * Format a number to a fixed number of decimal places.
+ *
+ * - If the input is a valid number, it rounds it to the specified number of decimals.
+ * - If the input is not a number, it returns 0.
+ *
+ * @param int - The input number to format
+ * @param i - The number of decimal places to keep
+ * @returns The formatted number with the given decimal places
+ *
+ * Example:
+ *   dp(12.3456, 2); // → 12.35
+ *   dp(99.999, 0);  // → 100
+ *   dp(NaN as any, 2); // → 0
+ */
 export declare const dp: (int: number, i: number) => number;
+/**
+ * Extract the Cloudinary public ID from a given Cloudinary image URL.
+ *
+ * A Cloudinary URL typically looks like:
+ *   https://res.cloudinary.com/<cloud_name>/image/upload/v<version>/<folder>/<fileName>.<ext>
+ *
+ * This function:
+ *  1. Removes the Cloudinary prefix (protocol, domain, resource type, and version).
+ *  2. Strips the file extension (e.g. ".jpg").
+ *  3. Decodes any URL-encoded characters (e.g. "%20" → " ").
+ *
+ * @param url - The full Cloudinary image URL
+ * @returns The extracted public ID (without extension), or an empty string on failure
+ *
+ * Example:
+ *   getCloudinaryPublicId("https://res.cloudinary.com/demo/image/upload/v12345/folder/my%20image.jpg")
+ *   // → "folder/my image"
+ */
 export declare const getCloudinaryPublicId: (url: string) => string;
+/**
+ * Build a query string from a key-value object.
+ *
+ * - Filters out keys/values that are empty or invalid (e.g. "", null, undefined, "null", "undefined").
+ * - Returns a string starting with "?" if there are valid params, otherwise returns an empty string.
+ *
+ * @param q - An object of query parameters
+ * @returns A properly formatted query string
+ *
+ * Example:
+ *   query({ limit: 10, skip: 20, sortBy: 'createdAt:desc', empty: '' });
+ *   // → "?limit=10&skip=20&sortBy=createdAt%3Adesc"
+ */
 export declare const query: (q: Record<string, any>) => string;
+/**
+ * Build a comma-separated string from a list of object keys.
+ *
+ * Useful when you need to select specific fields (e.g., for APIs, databases, or queries).
+ *
+ * @typeParam T - The type of the object whose keys are being selected
+ * @param keys - An array of keys from the object type T
+ * @returns A comma-separated string of the given keys
+ *
+ * Example:
+ *   type User = { id: string; name: string; email: string };
+ *   select<User>(['id', 'email']); // → "id,email"
+ */
 export declare const select: <T>(keys: (keyof T)[]) => string;
-export declare const extractImageSrcs: (htmlString: string) => any[];
+/**
+ * Extract all image `src` attribute values from an HTML string.
+ *
+ * Uses a regex to find <img> tags and capture the value of the `src` attribute.
+ *
+ * @param htmlString - The HTML string to search for image tags
+ * @returns An array of image source URLs
+ *
+ * Example:
+ *  extractImageSrcs('<img src="a.png"><div><img src="b.jpg"></div>');
+ *  // → ["a.png", "b.jpg"]
+ */
+export declare const extractImageSrcs: (htmlString: string) => string[];
+/**
+ * Generate a random alphanumeric string (uppercase letters + digits).
+ *
+ * @param length - The desired length of the generated string
+ * @returns A randomly generated string of the given length
+ *
+ * Example:
+ *  getRandomString(6) → "A9X2KQ"
+ */
 export declare const getRandomString: (length: number) => string;
+/**
+ * Check if a given URL points to a video file.
+ *
+ * Rules:
+ *  1. If the URL contains Cloudinary's `video/upload` path → treat as video.
+ *  2. Otherwise, check common video file extensions (mp4, webm, mov, avi, mkv).
+ *
+ * @param url - The URL string to check
+ * @returns true if the URL is a video, false otherwise
+ */
+export declare const isVideoUrl: (url: string) => boolean;

package/dist/index.js

@@ -1,29 +1,111 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRandomString = exports.extractImageSrcs = exports.select = exports.query = exports.getCloudinaryPublicId = exports.dp = exports.megaTrim = exports.superTrim = void 0;
+exports.isVideoUrl = exports.getRandomString = exports.extractImageSrcs = exports.select = exports.query = exports.getCloudinaryPublicId = exports.dp = exports.megaTrim = exports.superTrim = void 0;
+/**
+ * Clean up extra whitespace in a string.
+ *
+ * - Collapses multiple consecutive whitespace characters (spaces, tabs, newlines)
+ *   into a single space.
+ * - Trims leading and trailing whitespace.
+ *
+ * @param stringData - The input string to clean
+ * @returns The cleaned string with normalized spacing
+ *
+ * Example:
+ *   superTrim("   Hello    World   ");
+ *   // → "Hello World"
+ *
+ *   superTrim("Line1\n\nLine2");
+ *   // → "Line1 Line2"
+ */
 const superTrim = (stringData) => stringData.replace(/\s\s+/g, ' ').trim();
 exports.superTrim = superTrim;
+/**
+ * Remove extra whitespace from a string.
+ *
+ * - Collapses multiple consecutive whitespace characters into a single empty string (removes them completely).
+ * - Useful for cleaning up text where multiple spaces, tabs, or line breaks appear.
+ *
+ * @param stringData - The input string to clean
+ * @returns The string with extra whitespace removed
+ *
+ * Example:
+ *   megaTrim("Hello    World");   // → "HelloWorld"
+ *   megaTrim("Line1\n\n\nLine2"); // → "Line1Line2"
+ */
 const megaTrim = (stringData) => stringData.replace(/\s\s+/g, '');
 exports.megaTrim = megaTrim;
+/**
+ * Format a number to a fixed number of decimal places.
+ *
+ * - If the input is a valid number, it rounds it to the specified number of decimals.
+ * - If the input is not a number, it returns 0.
+ *
+ * @param int - The input number to format
+ * @param i - The number of decimal places to keep
+ * @returns The formatted number with the given decimal places
+ *
+ * Example:
+ *   dp(12.3456, 2); // → 12.35
+ *   dp(99.999, 0);  // → 100
+ *   dp(NaN as any, 2); // → 0
+ */
 const dp = (int, i) => (typeof int === 'number' ? +int.toFixed(i) : 0);
 exports.dp = dp;
+/**
+ * Extract the Cloudinary public ID from a given Cloudinary image URL.
+ *
+ * A Cloudinary URL typically looks like:
+ *   https://res.cloudinary.com/<cloud_name>/image/upload/v<version>/<folder>/<fileName>.<ext>
+ *
+ * This function:
+ *  1. Removes the Cloudinary prefix (protocol, domain, resource type, and version).
+ *  2. Strips the file extension (e.g. ".jpg").
+ *  3. Decodes any URL-encoded characters (e.g. "%20" → " ").
+ *
+ * @param url - The full Cloudinary image URL
+ * @returns The extracted public ID (without extension), or an empty string on failure
+ *
+ * Example:
+ *   getCloudinaryPublicId("https://res.cloudinary.com/demo/image/upload/v12345/folder/my%20image.jpg")
+ *   // → "folder/my image"
+ */
 const getCloudinaryPublicId = (url) => {
     try {
+        // Remove Cloudinary domain + "image/upload/v{version}/"
         const public_id_with_extension = url.replace(/^https?:\/\/res\.cloudinary\.com\/[^/]+\/image\/upload\/v\d+\//, '');
-        // Decode URL encoding (e.g., %20 → space)
+        // Decode URL encoding and strip extension (everything after the last ".")
         const public_id = decodeURIComponent(public_id_with_extension.replace(/\.[^.]+$/, ''));
         return public_id;
     }
-    catch (e) {
+    catch {
+        // In case of invalid URL or regex failure
         return '';
     }
 };
 exports.getCloudinaryPublicId = getCloudinaryPublicId;
+/**
+ * Build a query string from a key-value object.
+ *
+ * - Filters out keys/values that are empty or invalid (e.g. "", null, undefined, "null", "undefined").
+ * - Returns a string starting with "?" if there are valid params, otherwise returns an empty string.
+ *
+ * @param q - An object of query parameters
+ * @returns A properly formatted query string
+ *
+ * Example:
+ *   query({ limit: 10, skip: 20, sortBy: 'createdAt:desc', empty: '' });
+ *   // → "?limit=10&skip=20&sortBy=createdAt%3Adesc"
+ */
 const query = (q) => {
     try {
+        // Values considered "invalid" and should be filtered out
         const filter = ['', null, undefined, 'null', 'undefined'];
+        // Convert object to entries, filter out invalid keys/values
         const filtered = Object.entries(q).filter(([key, value]) => !filter.includes(key) && !filter.includes(value));
+        // Build query string using URLSearchParams
         const query = new URLSearchParams(filtered).toString();
+        // Prefix with "?" if there are any params
         return query ? `?${query}` : '';
     }
     catch (e) {
@@ -32,21 +114,88 @@ const query = (q) => {
     }
 };
 exports.query = query;
+/**
+ * Build a comma-separated string from a list of object keys.
+ *
+ * Useful when you need to select specific fields (e.g., for APIs, databases, or queries).
+ *
+ * @typeParam T - The type of the object whose keys are being selected
+ * @param keys - An array of keys from the object type T
+ * @returns A comma-separated string of the given keys
+ *
+ * Example:
+ *   type User = { id: string; name: string; email: string };
+ *   select<User>(['id', 'email']); // → "id,email"
+ */
 const select = (keys) => {
+    // Join all keys into a single comma-separated string
     return keys.join(',');
 };
 exports.select = select;
+/**
+ * Extract all image `src` attribute values from an HTML string.
+ *
+ * Uses a regex to find <img> tags and capture the value of the `src` attribute.
+ *
+ * @param htmlString - The HTML string to search for image tags
+ * @returns An array of image source URLs
+ *
+ * Example:
+ *  extractImageSrcs('<img src="a.png"><div><img src="b.jpg"></div>');
+ *  // → ["a.png", "b.jpg"]
+ */
 const extractImageSrcs = (htmlString) => {
+    // Find all <img> tags with a src attribute
     const imgTags = [...htmlString.matchAll(/<img\s+[^>]*src=["']([^"']+)["'][^>]*>/gi)];
+    // Map over regex matches and extract the first capture group (the src value)
     return imgTags.map(match => match[1]);
 };
 exports.extractImageSrcs = extractImageSrcs;
+/**
+ * Generate a random alphanumeric string (uppercase letters + digits).
+ *
+ * @param length - The desired length of the generated string
+ * @returns A randomly generated string of the given length
+ *
+ * Example:
+ *  getRandomString(6) → "A9X2KQ"
+ */
 const getRandomString = (length) => {
+    // Allowed characters: A–Z and 0–9
     const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
     let result = '';
+    // Loop for the requested length
     for (let i = 0; i < length; i++) {
+        // Pick a random index and append the corresponding character
         result += characters.charAt(Math.floor(Math.random() * characters.length));
     }
     return result;
 };
 exports.getRandomString = getRandomString;
+/**
+ * Check if a given URL points to a video file.
+ *
+ * Rules:
+ *  1. If the URL contains Cloudinary's `video/upload` path → treat as video.
+ *  2. Otherwise, check common video file extensions (mp4, webm, mov, avi, mkv).
+ *
+ * @param url - The URL string to check
+ * @returns true if the URL is a video, false otherwise
+ */
+const isVideoUrl = (url) => {
+    try {
+        const parsed = new URL(url);
+        // ✅ Rule 1: Cloudinary-specific pattern
+        if (parsed.pathname.includes('/video/upload/'))
+            return true;
+        // ✅ Rule 2: Check file extension
+        const videoExtensions = ['.mp4', '.webm', '.mov', '.avi', '.mkv'];
+        const lowerPath = parsed.pathname.toLowerCase();
+        return videoExtensions.some(ext => lowerPath.endsWith(ext));
+    }
+    catch {
+        // ❌ If URL parsing fails, assume it's not a valid video URL
+        return false;
+    }
+};
+exports.isVideoUrl = isVideoUrl;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ibiliaze/stringman",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "pub": "npm publish --access public",
-    "git": "git add .; git commit -m 'changes'; git tag -a v3.1.0 -m 'v3.1.0'; git push origin v3.1.0; git push",
+    "git": "git add .; git commit -m 'changes'; git tag -a v3.2.0 -m 'v3.2.0'; git push origin v3.2.0; git push",
     "push": "npm run build; npm run git; npm run pub"
   },
   "author": "Ibi Hasanli",

package/src/index.ts

@@ -1,26 +1,112 @@
-export const superTrim = (stringData: string) => stringData.replace(/\s\s+/g, ' ').trim();
-export const megaTrim = (stringData: string) => stringData.replace(/\s\s+/g, '');
-export const dp = (int: number, i: number) => (typeof int === 'number' ? +int.toFixed(i) : 0);
+/**
+ * Clean up extra whitespace in a string.
+ *
+ * - Collapses multiple consecutive whitespace characters (spaces, tabs, newlines)
+ *   into a single space.
+ * - Trims leading and trailing whitespace.
+ *
+ * @param stringData - The input string to clean
+ * @returns The cleaned string with normalized spacing
+ *
+ * Example:
+ *   superTrim("   Hello    World   ");
+ *   // → "Hello World"
+ *
+ *   superTrim("Line1\n\nLine2");
+ *   // → "Line1 Line2"
+ */
+export const superTrim = (stringData: string): string => stringData.replace(/\s\s+/g, ' ').trim();
+
+/**
+ * Remove extra whitespace from a string.
+ *
+ * - Collapses multiple consecutive whitespace characters into a single empty string (removes them completely).
+ * - Useful for cleaning up text where multiple spaces, tabs, or line breaks appear.
+ *
+ * @param stringData - The input string to clean
+ * @returns The string with extra whitespace removed
+ *
+ * Example:
+ *   megaTrim("Hello    World");   // → "HelloWorld"
+ *   megaTrim("Line1\n\n\nLine2"); // → "Line1Line2"
+ */
+export const megaTrim = (stringData: string): string => stringData.replace(/\s\s+/g, '');
+
+/**
+ * Format a number to a fixed number of decimal places.
+ *
+ * - If the input is a valid number, it rounds it to the specified number of decimals.
+ * - If the input is not a number, it returns 0.
+ *
+ * @param int - The input number to format
+ * @param i - The number of decimal places to keep
+ * @returns The formatted number with the given decimal places
+ *
+ * Example:
+ *   dp(12.3456, 2); // → 12.35
+ *   dp(99.999, 0);  // → 100
+ *   dp(NaN as any, 2); // → 0
+ */
+export const dp = (int: number, i: number): number => (typeof int === 'number' ? +int.toFixed(i) : 0);
+
+/**
+ * Extract the Cloudinary public ID from a given Cloudinary image URL.
+ *
+ * A Cloudinary URL typically looks like:
+ *   https://res.cloudinary.com/<cloud_name>/image/upload/v<version>/<folder>/<fileName>.<ext>
+ *
+ * This function:
+ *  1. Removes the Cloudinary prefix (protocol, domain, resource type, and version).
+ *  2. Strips the file extension (e.g. ".jpg").
+ *  3. Decodes any URL-encoded characters (e.g. "%20" → " ").
+ *
+ * @param url - The full Cloudinary image URL
+ * @returns The extracted public ID (without extension), or an empty string on failure
+ *
+ * Example:
+ *   getCloudinaryPublicId("https://res.cloudinary.com/demo/image/upload/v12345/folder/my%20image.jpg")
+ *   // → "folder/my image"
+ */
 export const getCloudinaryPublicId = (url: string): string => {
   try {
+    // Remove Cloudinary domain + "image/upload/v{version}/"
     const public_id_with_extension = url.replace(/^https?:\/\/res\.cloudinary\.com\/[^/]+\/image\/upload\/v\d+\//, '');
 
-    // Decode URL encoding (e.g., %20 → space)
+    // Decode URL encoding and strip extension (everything after the last ".")
     const public_id = decodeURIComponent(public_id_with_extension.replace(/\.[^.]+$/, ''));
 
     return public_id;
-  } catch (e) {
+  } catch {
+    // In case of invalid URL or regex failure
     return '';
   }
 };
+
+/**
+ * Build a query string from a key-value object.
+ *
+ * - Filters out keys/values that are empty or invalid (e.g. "", null, undefined, "null", "undefined").
+ * - Returns a string starting with "?" if there are valid params, otherwise returns an empty string.
+ *
+ * @param q - An object of query parameters
+ * @returns A properly formatted query string
+ *
+ * Example:
+ *   query({ limit: 10, skip: 20, sortBy: 'createdAt:desc', empty: '' });
+ *   // → "?limit=10&skip=20&sortBy=createdAt%3Adesc"
+ */
 export const query = (q: Record<string, any>): string => {
   try {
+    // Values considered "invalid" and should be filtered out
     const filter = ['', null, undefined, 'null', 'undefined'];
 
+    // Convert object to entries, filter out invalid keys/values
     const filtered = Object.entries(q).filter(([key, value]) => !filter.includes(key) && !filter.includes(value));
 
+    // Build query string using URLSearchParams
     const query = new URLSearchParams(filtered as [string, string][]).toString();
 
+    // Prefix with "?" if there are any params
     return query ? `?${query}` : '';
   } catch (e) {
     console.error(e);
@@ -28,21 +114,90 @@ export const query = (q: Record<string, any>): string => {
   }
 };
 
+/**
+ * Build a comma-separated string from a list of object keys.
+ *
+ * Useful when you need to select specific fields (e.g., for APIs, databases, or queries).
+ *
+ * @typeParam T - The type of the object whose keys are being selected
+ * @param keys - An array of keys from the object type T
+ * @returns A comma-separated string of the given keys
+ *
+ * Example:
+ *   type User = { id: string; name: string; email: string };
+ *   select<User>(['id', 'email']); // → "id,email"
+ */
 export const select = <T>(keys: (keyof T)[]): string => {
+  // Join all keys into a single comma-separated string
   return keys.join(',');
 };
 
-export const extractImageSrcs = (htmlString: string) => {
+/**
+ * Extract all image `src` attribute values from an HTML string.
+ *
+ * Uses a regex to find <img> tags and capture the value of the `src` attribute.
+ *
+ * @param htmlString - The HTML string to search for image tags
+ * @returns An array of image source URLs
+ *
+ * Example:
+ *  extractImageSrcs('<img src="a.png"><div><img src="b.jpg"></div>');
+ *  // → ["a.png", "b.jpg"]
+ */
+export const extractImageSrcs = (htmlString: string): string[] => {
+  // Find all <img> tags with a src attribute
   const imgTags = [...htmlString.matchAll(/<img\s+[^>]*src=["']([^"']+)["'][^>]*>/gi)];
+
+  // Map over regex matches and extract the first capture group (the src value)
   return imgTags.map(match => match[1]);
 };
 
-export const getRandomString = (length: number) => {
+/**
+ * Generate a random alphanumeric string (uppercase letters + digits).
+ *
+ * @param length - The desired length of the generated string
+ * @returns A randomly generated string of the given length
+ *
+ * Example:
+ *  getRandomString(6) → "A9X2KQ"
+ */
+export const getRandomString = (length: number): string => {
+  // Allowed characters: A–Z and 0–9
   const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
   let result = '';
+
+  // Loop for the requested length
   for (let i = 0; i < length; i++) {
+    // Pick a random index and append the corresponding character
     result += characters.charAt(Math.floor(Math.random() * characters.length));
   }
 
   return result;
 };
+
+/**
+ * Check if a given URL points to a video file.
+ *
+ * Rules:
+ *  1. If the URL contains Cloudinary's `video/upload` path → treat as video.
+ *  2. Otherwise, check common video file extensions (mp4, webm, mov, avi, mkv).
+ *
+ * @param url - The URL string to check
+ * @returns true if the URL is a video, false otherwise
+ */
+export const isVideoUrl = (url: string): boolean => {
+  try {
+    const parsed = new URL(url);
+
+    // ✅ Rule 1: Cloudinary-specific pattern
+    if (parsed.pathname.includes('/video/upload/')) return true;
+
+    // ✅ Rule 2: Check file extension
+    const videoExtensions = ['.mp4', '.webm', '.mov', '.avi', '.mkv'];
+    const lowerPath = parsed.pathname.toLowerCase();
+    return videoExtensions.some(ext => lowerPath.endsWith(ext));
+  } catch {
+    // ❌ If URL parsing fails, assume it's not a valid video URL
+    return false;
+  }
+};