feat: add id and validate utils

Author: cyber-hari

package-lock.json

@@ -34,8 +34,10 @@
   "dependencies": {
     "abort-controller": "^3.0.0",
     "mysql2": "^3.14.3",
+    "nanoid": "^5.1.5",
     "node-fetch": "^3.3.2",
-    "pino": "^9.7.0"
+    "pino": "^9.7.0",
+    "ulid": "^3.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.2.0",

package.json

@@ -0,0 +1,57 @@
+import { randomUUID } from "crypto";
+import { ulid } from "ulid";
+import { nanoid } from "nanoid";
+
+/**
+ * Generates a UUID v4 string (RFC 4122).
+ *
+ * @returns {string} UUID v4 (e.g., 'c0de1234-5678-9abc-def0-123456789abc')
+ */
+export function uuid(): string {
+  return randomUUID();
+}
+
+/**
+ * Generates a ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * @returns {string} ULID string (26 chars, Crockford Base32, e.g., '01H7ZXS9FJKPX06P1AYZKCGHQF').
+ */
+export function ulidString(): string {
+  return ulid();
+}
+
+/**
+ * Generates a nanoid string (URL-friendly, collision-resistant, customizable size).
+ *
+ * @param {number} [size=21] - Number of characters for the ID (default: 21).
+ * @returns {string} nanoid string.
+ */
+export function nanoId(size: number = 21): string {
+  return nanoid(size);
+}
+
+/**
+ * Generates a cryptographically strong random hex string.
+ *
+ * @param {number} byteLength - Number of random bytes (default: 16 → 32 hex chars).
+ * @returns {string} Random hex string.
+ */
+export function randomHex(byteLength: number = 16): string {
+  // Node: crypto.getRandomValues is not available; use randomBytes if needed.
+  // If using browser target, replace this impl accordingly.
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(byteLength)))
+    .toString("hex")
+    .slice(0, byteLength * 2);
+}
+
+/**
+ * Generates a random integer between min (inclusive) and max (inclusive).
+ *
+ * @param {number} min - Minimum value.
+ * @param {number} max - Maximum value.
+ * @returns {number} Random integer in range.
+ */
+export function randomInt(min: number, max: number): number {
+  const range = max - min + 1;
+  return Math.floor(Math.random() * range) + min;
+}

src/utils/id.utils.ts

@@ -0,0 +1,100 @@
+/**
+ * Collection of common validation helpers for strings, numbers, email, UUID, etc.
+ */
+
+/**
+ * Checks if a string is a valid email address.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid email, else false.
+ */
+export function isEmail(str: string): boolean {
+  // RFC 5322 official standard is more complex—this is practical.
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(str);
+}
+
+/**
+ * Checks if a string is a valid UUID (versions 1-5).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid UUID, else false.
+ */
+export function isUUID(str: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    str,
+  );
+}
+
+/**
+ * Checks if a string is a valid URL.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid URL, else false.
+ */
+export function isURL(str: string): boolean {
+  try {
+    new URL(str);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks if a string is a valid international phone number (E.164 or common patterns).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if looks like a phone number.
+ */
+export function isPhone(str: string): boolean {
+  // E.164 or basic with spaces, dashes, parentheses
+  return /^(\+?[1-9]\d{1,14}|(\+?\d{1,3}[-.\s]?)?\(?\d{2,4}\)?([-\s]?\d{3,4}){2,})$/.test(
+    str,
+  );
+}
+
+/**
+ * Checks if a string is strictly alphanumeric (letters/numbers only).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if alphanumeric.
+ */
+export function isAlphanumeric(str: string): boolean {
+  return /^[a-z0-9]+$/i.test(str);
+}
+
+/**
+ * Checks if a string or number can be safely parsed to a number.
+ *
+ * @param {string | number} value - The value to check.
+ * @returns {boolean} True if the value is numeric.
+ */
+export function isNumeric(value: string | number): boolean {
+  if (typeof value === "number") return !isNaN(value) && isFinite(value);
+  return (
+    typeof value === "string" && value.trim() !== "" && !isNaN(Number(value))
+  );
+}
+
+/**
+ * Checks if a string is a valid hex color code (e.g. #FFF or #FFFFFF).
+ *
+ * @param {string} str - Input string.
+ * @returns {boolean}
+ */
+export function isHexColor(str: string): boolean {
+  return /^#([a-f0-9]{6}|[a-f0-9]{3})$/i.test(str);
+}
+
+/**
+ * Checks if a string is a valid ISO8601 date string.
+ *
+ * @param {string} str - Input string.
+ * @returns {boolean}
+ */
+export function isISODate(str: string): boolean {
+  // YYYY-MM-DD, extended, or with time portion
+  return /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(?:\.\d+)?(Z|[\+|-]\d{2}:\d{2})?)?$/.test(
+    str,
+  );
+}