@germondai/ts-utils 0.0.1

package/README.md

@@ -0,0 +1,15 @@
+# @germondai/ts-utils
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.2.2. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/dist/module.d.ts

@@ -0,0 +1 @@
+export * from './runtime';

package/dist/module.js

@@ -0,0 +1,244 @@
+// src/runtime/collection.ts
+var hasDuplicates = (array, keyExtractor) => {
+  const seen = new Set;
+  for (const item of array) {
+    const key = keyExtractor ? keyExtractor(item) : item;
+    if (seen.has(key))
+      return true;
+    seen.add(key);
+  }
+  return false;
+};
+var uniqueArray = (array) => [...new Set(array)];
+// src/runtime/constants.ts
+var SUPPORTED_DISPLAYABLE_MEDIA_TYPES = {
+  images: [
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/svg+xml",
+    "image/avif",
+    "image/apng"
+  ],
+  videos: [
+    "video/mp4",
+    "video/webm",
+    "video/ogg",
+    "video/quicktime"
+  ]
+};
+// src/runtime/convertor.ts
+var toCamelCase = (input) => {
+  const words = input.toLowerCase().split(/[\s_-]+/).filter(Boolean);
+  return words.map((word, index) => index === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)).join("");
+};
+var toPascalCase = (input) => input.toLowerCase().split(/[\s_-]+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+var toSnakeCase = (input) => input.toLowerCase().split(/[\s-]+/).filter(Boolean).join("_");
+var toKebabCase = (input) => input.toLowerCase().split(/[\s_]+/).filter(Boolean).join("-");
+var toTitleCase = (input) => input.toLowerCase().split(/\s+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+var toSentenceCase = (input) => {
+  const lower = input.toLowerCase();
+  return lower.charAt(0).toUpperCase() + lower.slice(1);
+};
+var toConstantCase = (input) => toSnakeCase(input).toUpperCase();
+var toggleCase = (input) => input.split("").map((char) => char === char.toUpperCase() ? char.toLowerCase() : char.toUpperCase()).join("");
+var capitalize = (str) => str.length > 0 ? str.charAt(0).toUpperCase() + str.slice(1).toLowerCase() : str;
+var truncate = (text, maxLength, ellipsis = false) => {
+  if (text.length <= maxLength)
+    return text;
+  return ellipsis ? text.slice(0, maxLength - 3) + "..." : text.slice(0, maxLength);
+};
+var slugify = (title, length = 64) => title.toString().normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().trim().replace(/\s+/g, "-").replace(/[^\w-]+/g, "").replace(/--+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, length);
+var stripTags = (html) => html.replace(/<\/?[^>]+(>|$)/g, "");
+var escapeHTML = (str) => {
+  const escapeMap = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#039;"
+  };
+  return str.replace(/[&<>"']/g, (char) => escapeMap[char] || char);
+};
+// src/runtime/data.ts
+var clone = (data) => JSON.parse(JSON.stringify(data));
+// src/runtime/errors.ts
+var catchError = (promise, errorsToCatch) => promise().then((data) => ({ data, ok: true })).catch((error) => {
+  if (errorsToCatch === undefined || errorsToCatch.some((e) => error instanceof e))
+    return { error, ok: false };
+  throw error;
+});
+// src/runtime/math.ts
+var rand = (n, m = 0) => Math.floor(Math.random() * (m - n + 1)) + n;
+var percentage = (value, maxValue, decimalPlaces = 2) => {
+  if (maxValue === 0)
+    return 0;
+  const percent = value / maxValue * 100;
+  return Number(percent.toFixed(decimalPlaces));
+};
+var clamp = (num, min, max) => Math.min(Math.max(num, min), max);
+var formatNumber = (num) => num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+// src/runtime/media.ts
+var isSupportedDisplayableMedia = (mime, type = { image: true, video: true }) => type.image && SUPPORTED_DISPLAYABLE_MEDIA_TYPES.images.includes(mime) || type.video && SUPPORTED_DISPLAYABLE_MEDIA_TYPES.videos.includes(mime);
+// src/runtime/promise.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// src/runtime/regex.ts
+var isEmail = (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+var isUrl = (value) => /^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$/.test(value);
+var isPhoneNumber = (value) => /^\+?(\d{1,3})?[-. (]*\d{1,4}[-. )]*\d{1,4}[-. ]*\d{1,9}$/.test(value);
+var isHex = (value) => /^[A-Fa-f0-9]+$/.test(value);
+var isHexColor = (value) => /^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$/.test(value);
+var isIPv4 = (value) => /^(25[0-5]|2[0-4][0-9]|1?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|1?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|1?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|1?[0-9][0-9]?)$/.test(value);
+var isIPv6 = (value) => /^(?:[A-F0-9]{1,4}:){7}[A-F0-9]{1,4}$/i.test(value);
+var isMacAddress = (value) => /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/.test(value);
+var isUUID = (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+var isCreditCard = (value) => /^(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|6(?:011|5[0-9]{2})[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|(?:2131|1800|35\d{3})\d{11})$/.test(value);
+var isDomain = (value) => /^(?!:\/\/)([a-zA-Z0-9-_]{1,63}\.)+[a-zA-Z]{2,63}$/.test(value);
+var isPostalCode = (value) => /^[A-Za-z0-9\s-]{3,10}$/.test(value);
+var isISODate = (value) => /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/.test(value);
+var isJson = (value) => {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var isBase64 = (value) => /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+var isSlug = (value) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+// src/runtime/size.ts
+var formatBytes = (bytes, decimals = 2) => {
+  if (bytes === 0)
+    return "0 Bytes";
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  const size = parseFloat((bytes / Math.pow(k, i)).toFixed(dm));
+  return `${size} ${sizes[i]}`;
+};
+// src/runtime/time.ts
+var formatTime = (seconds) => {
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor(seconds % 3600 / 60);
+  const secs = seconds % 60;
+  const minutesStr = minutes.toString().padStart(2, "0");
+  const secsStr = secs.toString().padStart(2, "0");
+  if (hours > 0)
+    return `${hours}:${minutesStr}:${secsStr}`;
+  if (minutes > 0)
+    return `${minutes}:${secsStr}`;
+  return `0:${secsStr}`;
+};
+var formatDuration = (ms) => {
+  const sec = Math.floor(ms / 1000);
+  const min = Math.floor(sec / 60);
+  const hrs = Math.floor(min / 60);
+  const days = Math.floor(hrs / 24);
+  if (days > 0)
+    return `${days}d ${hrs % 24}h`;
+  if (hrs > 0)
+    return `${hrs}h ${min % 60}m`;
+  if (min > 0)
+    return `${min}m ${sec % 60}s`;
+  return `${sec}s`;
+};
+// src/runtime/type.ts
+var isPrimitive = (value) => value === null || value === undefined || typeof value !== "object" && typeof value !== "function";
+var isObject = (value) => value !== null && typeof value === "object" && value.constructor === Object;
+var isArray = (value) => Array.isArray(value);
+var isEmpty = (value) => {
+  if (value === undefined || value === null)
+    return true;
+  if (isArray(value) || typeof value === "string")
+    return value.length === 0;
+  if (isObject(value))
+    return Object.keys(value).length === 0;
+  return false;
+};
+// src/runtime/url.ts
+var getQueryParams = (urlString) => {
+  const url = new URL(urlString);
+  const params = {};
+  url.searchParams.forEach((value, key) => {
+    params[key] = value;
+  });
+  return params;
+};
+var updateQueryParam = (urlString, key, value) => {
+  const url = new URL(urlString);
+  url.searchParams.set(key, value);
+  return url.toString();
+};
+var removeQueryParam = (urlString, key) => {
+  const url = new URL(urlString);
+  url.searchParams.delete(key);
+  return url.toString();
+};
+var buildUrl = (baseUrl, path, queryParams) => {
+  const url = new URL(baseUrl);
+  if (path) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    url.pathname = `${url.pathname.replace(/\/$/, "")}${normalizedPath}`;
+  }
+  if (queryParams) {
+    Object.entries(queryParams).forEach(([key, value]) => {
+      url.searchParams.set(key, String(value));
+    });
+  }
+  return url.toString();
+};
+export {
+  updateQueryParam,
+  uniqueArray,
+  truncate,
+  toggleCase,
+  toTitleCase,
+  toSnakeCase,
+  toSentenceCase,
+  toPascalCase,
+  toKebabCase,
+  toConstantCase,
+  toCamelCase,
+  stripTags,
+  slugify,
+  sleep,
+  removeQueryParam,
+  rand,
+  percentage,
+  isUrl,
+  isUUID,
+  isSupportedDisplayableMedia,
+  isSlug,
+  isPrimitive,
+  isPostalCode,
+  isPhoneNumber,
+  isObject,
+  isMacAddress,
+  isJson,
+  isISODate,
+  isIPv6,
+  isIPv4,
+  isHexColor,
+  isHex,
+  isEmpty,
+  isEmail,
+  isDomain,
+  isCreditCard,
+  isBase64,
+  isArray,
+  hasDuplicates,
+  getQueryParams,
+  formatTime,
+  formatNumber,
+  formatDuration,
+  formatBytes,
+  escapeHTML,
+  clone,
+  clamp,
+  catchError,
+  capitalize,
+  buildUrl,
+  SUPPORTED_DISPLAYABLE_MEDIA_TYPES
+};

package/dist/runtime/case.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Converts a string to camelCase.
+ * Example: "hello world" → "helloWorld"
+ * @param input The input string.
+ * @returns The camelCase version of the input.
+ */
+export declare const toCamelCase: (input: string) => string;
+/**
+ * Converts a string to PascalCase.
+ * Example: "hello world" → "HelloWorld"
+ * @param input The input string.
+ * @returns The PascalCase version of the input.
+ */
+export declare const toPascalCase: (input: string) => string;
+/**
+ * Converts a string to snake_case.
+ * Example: "hello world" → "hello_world"
+ * @param input The input string.
+ * @returns The snake_case version of the input.
+ */
+export declare const toSnakeCase: (input: string) => string;
+/**
+ * Converts a string to kebab-case.
+ * Example: "hello world" → "hello-world"
+ * @param input The input string.
+ * @returns The kebab-case version of the input.
+ */
+export declare const toKebabCase: (input: string) => string;
+/**
+ * Converts a string to title case.
+ * Example: "hello world" → "Hello World"
+ * Splits the input by whitespace, lowercases it, then capitalizes each word.
+ * @param input The input string.
+ * @returns The title-cased string.
+ */
+export declare const toTitleCase: (input: string) => string;
+/**
+ * Converts a string to sentence case.
+ * Example: "hello world" → "Hello world"
+ * Lowercases the entire string then capitalizes only the first letter.
+ * @param input The input string.
+ * @returns The sentence-cased string.
+ */
+export declare const toSentenceCase: (input: string) => string;
+/**
+ * Toggles the case of each character in the string.
+ * Example: "Hello" → "hELLO"
+ * For each character, if it's uppercase it becomes lowercase, and vice versa.
+ * @param input The input string.
+ * @returns The string with toggled character cases.
+ */
+export declare const toggleCase: (input: string) => string;
+/**
+ * Converts a string to constant case (screaming snake case).
+ * Example: "hello world" → "HELLO_WORLD"
+ * This builds on the snake_case conversion and then converts the result to uppercase.
+ * @param input The input string.
+ * @returns The constant-cased string.
+ */
+export declare const toConstantCase: (input: string) => string;

package/dist/runtime/collection.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Checks if an array contains duplicate values.
+ *
+ * @param array - The array to check for duplicates.
+ * @returns True if the array contains duplicates, false otherwise.
+ *
+ * @example
+ * hasDuplicates([1, 2, 3, 4, 1]); // true
+ * hasDuplicates(['a', 'b', 'c']); // false
+ * hasDuplicates([{ id: 1 }, { id: 2 }, { id: 1 }], (item) => item.id); // true
+ */
+export declare const hasDuplicates: <T>(array: T[], keyExtractor?: (item: T) => unknown) => boolean;
+/**
+ * Removes duplicates from an array.
+ *
+ * @param array - The array to process.
+ * @returns A new array without duplicates.
+ */
+export declare const uniqueArray: <T>(array: T[]) => T[];

package/dist/runtime/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const SUPPORTED_DISPLAYABLE_MEDIA_TYPES: {
+    images: string[];
+    videos: string[];
+};

package/dist/runtime/convertor.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Converts a string to camelCase.
+ * Example: "hello world" → "helloWorld"
+ * @param input The input string.
+ * @returns The camelCase version of the input.
+ */
+export declare const toCamelCase: (input: string) => string;
+/**
+ * Converts a string to PascalCase.
+ * Example: "hello world" → "HelloWorld"
+ * @param input The input string.
+ * @returns The PascalCase version of the input.
+ */
+export declare const toPascalCase: (input: string) => string;
+/**
+ * Converts a string to snake_case.
+ * Example: "hello world" → "hello_world"
+ * @param input The input string.
+ * @returns The snake_case version of the input.
+ */
+export declare const toSnakeCase: (input: string) => string;
+/**
+ * Converts a string to kebab-case.
+ * Example: "hello world" → "hello-world"
+ * @param input The input string.
+ * @returns The kebab-case version of the input.
+ */
+export declare const toKebabCase: (input: string) => string;
+/**
+ * Converts a string to title case.
+ * Example: "hello world" → "Hello World"
+ * Splits the input by whitespace, lowercases it, then capitalizes each word.
+ * @param input The input string.
+ * @returns The title-cased string.
+ */
+export declare const toTitleCase: (input: string) => string;
+/**
+ * Converts a string to sentence case.
+ * Example: "hello world" → "Hello world"
+ * Lowercases the entire string then capitalizes only the first letter.
+ * @param input The input string.
+ * @returns The sentence-cased string.
+ */
+export declare const toSentenceCase: (input: string) => string;
+/**
+ * Converts a string to constant case (screaming snake case).
+ * Example: "hello world" → "HELLO_WORLD"
+ * This builds on the snake_case conversion and then converts the result to uppercase.
+ * @param input The input string.
+ * @returns The constant-cased string.
+ */
+export declare const toConstantCase: (input: string) => string;
+/**
+ * Toggles the case of each character in the string.
+ * Example: "Hello" → "hELLO"
+ * For each character, if it's uppercase it becomes lowercase, and vice versa.
+ * @param input The input string.
+ * @returns The string with toggled character cases.
+ */
+export declare const toggleCase: (input: string) => string;
+/**
+ * Capitalizes the first character of a string and lowercases the remainder.
+ *
+ * @param str - The string to capitalize.
+ * @returns The capitalized string.
+ */
+export declare const capitalize: (str: string) => string;
+/**
+ * Truncates a string to a maximum length.
+ *
+ * If the string exceeds the maximum length, it will be cut off.
+ * Optionally, an ellipsis ("...") is appended.
+ *
+ * @param text - The text to truncate.
+ * @param maxLength - The maximum allowed length.
+ * @param ellipsis - Whether to append "..." if truncated (default is false).
+ * @returns The truncated string.
+ */
+export declare const truncate: (text: string, maxLength: number, ellipsis?: boolean) => string;
+/**
+ * Generates a URL-friendly slug from a given string.
+ *
+ * The function normalizes accented characters, converts the string to lowercase,
+ * trims whitespace, replaces spaces with hyphens, removes invalid characters,
+ * and limits the slug length.
+ *
+ * @param title - The input string to slugify.
+ * @param length - Maximum length of the slug (default is 64).
+ * @returns The slugified string.
+ */
+export declare const slugify: (title: string, length?: number) => string;
+/**
+ * Strips HTML tags from a string.
+ *
+ * @param html - The HTML string.
+ * @returns The string without HTML tags.
+ */
+export declare const stripTags: (html: string) => string;
+/**
+ * Escapes special characters in a string to make it safe for inclusion in HTML.
+ * Converts characters like `<`, `>`, `&`, `"`, and `'` into their HTML entity equivalents.
+ *
+ * @param str - The input string to escape.
+ * @returns The HTML-escaped string.
+ */
+export declare const escapeHTML: (str: string) => string;

package/dist/runtime/data.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates a deep clone of the given data using JSON serialization.
+ *
+ * **Note:** This method does not support cloning functions, dates, or undefined values.
+ *
+ * @param data - The data to clone.
+ * @returns A deep copy of the data.
+ */
+export declare const clone: <T>(data: T) => T;

package/dist/runtime/date.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Formats a duration in seconds into a human-readable time string.
+ *
+ * - If the duration is one hour or more: "H:MM:SS"
+ * - If the duration is less than an hour but at least one minute: "M:SS"
+ * - Otherwise: "0:SS"
+ *
+ * @param seconds - The total number of seconds.
+ * @returns The formatted time string.
+ */
+export declare const formatTime: (seconds: number) => string;

package/dist/runtime/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wraps a promise and catches specified errors.
+ *
+ * Returns an object containing the resolved data or the caught error.
+ * If the error is not one of the specified errors to catch, it is re-thrown.
+ *
+ * @template T - The type of data returned by the promise.
+ * @template E - The error type(s) to catch.
+ * @param promise - A function that returns a promise.
+ * @param errorsToCatch - Optional array of error constructors to catch.
+ * @returns A promise resolving to an object with either the data or an error.
+ */
+export declare const catchError: <T, E extends new (message?: string) => Error>(promise: () => Promise<T>, errorsToCatch?: E[]) => Promise<{
+    data?: T;
+    ok: boolean;
+    error?: InstanceType<E>;
+}>;

package/dist/runtime/index.d.ts

@@ -0,0 +1,13 @@
+export * from './collection';
+export * from './constants';
+export * from './convertor';
+export * from './data';
+export * from './errors';
+export * from './math';
+export * from './media';
+export * from './promise';
+export * from './regex';
+export * from './size';
+export * from './time';
+export * from './type';
+export * from './url';

package/dist/runtime/math.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generates a random integer between n and m (inclusive).
+ *
+ * **Note:** Ensure that `m` is greater than or equal to `n`.
+ *
+ * @param n - The lower bound.
+ * @param m - The upper bound (default is 0).
+ * @returns A random integer between n and m.
+ */
+export declare const rand: (n: number, m?: number) => number;
+/**
+ * Calculates the percentage of a number relative to a maximum number.
+ *
+ * @param value - The current value.
+ * @param maxValue - The maximum possible value.
+ * @param decimalPlaces - Number of decimal places to round to (default: 2).
+ * @returns The calculated percentage, or 0 if maxValue is 0.
+ */
+export declare const percentage: (value: number, maxValue: number, decimalPlaces?: number) => number;
+/**
+ * Clamps a number within a specified range.
+ *
+ * @param num - The number to clamp.
+ * @param min - The minimum value.
+ * @param max - The maximum value.
+ * @returns The clamped value.
+ */
+export declare const clamp: (num: number, min: number, max: number) => number;
+/**
+ * Formats a number with commas for thousands.
+ *
+ * @param num - The number to format.
+ * @returns A string with formatted number (e.g., "1,234,567").
+ */
+export declare const formatNumber: (num: number) => string;

package/dist/runtime/media.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks if a given MIME type is supported as displayable media.
+ *
+ * Uses the SUPPORTED_DISPLAYABLE_MEDIA_TYPES constant from './constants'.
+ *
+ * @param mime - The MIME type of the file.
+ * @param type - An object specifying if images and/or videos should be checked (default is both).
+ * @returns True if the MIME type is supported, false otherwise.
+ */
+export declare const isSupportedDisplayableMedia: (mime: File["type"], type?: {
+    image?: boolean;
+    video?: boolean;
+}) => boolean | undefined;

package/dist/runtime/promise.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Waits for a given number of milliseconds.
+ *
+ * @param ms - The number of milliseconds to wait.
+ * @returns A promise that resolves after the delay.
+ */
+export declare const sleep: (ms: number) => Promise<void>;

package/dist/runtime/regex.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Checks if a given string is a valid email address.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid email, false otherwise.
+ *
+ * @example
+ * isEmail('test@example.com'); // true
+ * isEmail('invalid-email'); // false
+ */
+export declare const isEmail: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid URL.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid URL, false otherwise.
+ *
+ * @example
+ * isUrl('https://example.com'); // true
+ * isUrl('ftp://files.example.com'); // true
+ * isUrl('invalid-url'); // false
+ */
+export declare const isUrl: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid phone number (supports various formats).
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid phone number, false otherwise.
+ *
+ * @example
+ * isPhoneNumber('+1 (555) 555-5555'); // true
+ * isPhoneNumber('123456'); // false
+ */
+export declare const isPhoneNumber: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid hexadecimal string.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid hexadecimal, false otherwise.
+ *
+ * @example
+ * isHex('1A3F'); // true
+ * isHex('XYZ'); // false
+ */
+export declare const isHex: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid hex color code.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid hex color, false otherwise.
+ *
+ * @example
+ * isHexColor('#ff5733'); // true
+ * isHexColor('rgb(255, 87, 51)'); // false
+ */
+export declare const isHexColor: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid IPv4 address.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid IPv4 address, false otherwise.
+ *
+ * @example
+ * isIPv4('192.168.1.1'); // true
+ * isIPv4('999.999.999.999'); // false
+ */
+export declare const isIPv4: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid IPv6 address.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid IPv6 address, false otherwise.
+ *
+ * @example
+ * isIPv6('2001:0db8:85a3:0000:0000:8a2e:0370:7334'); // true
+ * isIPv6('InvalidIPv6'); // false
+ */
+export declare const isIPv6: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid MAC address.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid MAC address, false otherwise.
+ *
+ * @example
+ * isMacAddress('00:1A:2B:3C:4D:5E'); // true
+ * isMacAddress('invalid-mac'); // false
+ */
+export declare const isMacAddress: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid UUID (v4 format).
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid UUID, false otherwise.
+ *
+ * @example
+ * isUUID('123e4567-e89b-12d3-a456-426614174000'); // true
+ * isUUID('invalid-uuid'); // false
+ */
+export declare const isUUID: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid credit card number (basic validation).
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid credit card number, false otherwise.
+ *
+ * @example
+ * isCreditCard('4111 1111 1111 1111'); // true
+ * isCreditCard('1234567890123456'); // false
+ */
+export declare const isCreditCard: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid domain name.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid domain, false otherwise.
+ *
+ * @example
+ * isDomain('example.com'); // true
+ * isDomain('sub.example.co.uk'); // true
+ * isDomain('invalid_domain'); // false
+ */
+export declare const isDomain: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid postal/ZIP code (supports various formats).
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid postal code, false otherwise.
+ *
+ * @example
+ * isPostalCode('12345'); // true (US)
+ * isPostalCode('12345-6789'); // true (US extended)
+ * isPostalCode('SW1A 1AA'); // true (UK)
+ * isPostalCode('invalid_code'); // false
+ */
+export declare const isPostalCode: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid date in YYYY-MM-DD format.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid date, false otherwise.
+ *
+ * @example
+ * isISODate('2024-02-12'); // true
+ * isISODate('2024-13-01'); // false
+ */
+export declare const isISODate: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid JSON string.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is valid JSON, false otherwise.
+ *
+ * @example
+ * isJson('{"name": "John"}'); // true
+ * isJson('{invalid}'); // false
+ */
+export declare const isJson: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid Base64-encoded string.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is valid Base64, false otherwise.
+ *
+ * @example
+ * isBase64('U29tZSB0ZXh0'); // true
+ * isBase64('Invalid!'); // false
+ */
+export declare const isBase64: (value: string) => boolean;
+/**
+ * Checks if a given string is a valid slug.
+ *
+ * @param value - The string to validate.
+ * @returns True if the string is a valid slug, false otherwise.
+ *
+ * @example
+ * isSlug('valid-slug-123'); // true
+ * isSlug('Invalid Slug!'); // false
+ */
+export declare const isSlug: (value: string) => boolean;

package/dist/runtime/size.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts a file size in bytes into a human-readable string with appropriate units.
+ *
+ * The function supports sizes in Bytes, KB, MB, GB, TB, and PB.
+ *
+ * @param bytes - The file size in bytes.
+ * @param decimals - The number of decimal places to round to (default is 2).
+ * @returns A string representing the file size (e.g., "1.23 MB").
+ */
+export declare const formatBytes: (bytes: number, decimals?: number) => string;

package/dist/runtime/string.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Capitalizes the first character of a string and lowercases the remainder.
+ *
+ * @param str - The string to capitalize.
+ * @returns The capitalized string.
+ */
+export declare const capitalize: (str: string) => string;
+/**
+ * Truncates a string to a maximum length.
+ *
+ * If the string exceeds the maximum length, it will be cut off.
+ * Optionally, an ellipsis ("...") is appended.
+ *
+ * @param text - The text to truncate.
+ * @param maxLength - The maximum allowed length.
+ * @param ellipsis - Whether to append "..." if truncated (default is false).
+ * @returns The truncated string.
+ */
+export declare const truncate: (text: string, maxLength: number, ellipsis?: boolean) => string;
+/**
+ * Generates a URL-friendly slug from a given string.
+ *
+ * The function normalizes accented characters, converts the string to lowercase,
+ * trims whitespace, replaces spaces with hyphens, removes invalid characters,
+ * and limits the slug length.
+ *
+ * @param title - The input string to slugify.
+ * @param length - Maximum length of the slug (default is 64).
+ * @returns The slugified string.
+ */
+export declare const slugify: (title: string, length?: number) => string;
+/**
+ * Strips HTML tags from a string.
+ *
+ * @param html - The HTML string.
+ * @returns The string without HTML tags.
+ */
+export declare const stripTags: (html: string) => string;

package/dist/runtime/time.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Formats a duration in seconds into a human-readable time string.
+ *
+ * - If the duration is one hour or more: "H:MM:SS"
+ * - If the duration is less than an hour but at least one minute: "M:SS"
+ * - Otherwise: "0:SS"
+ *
+ * @param seconds - The total number of seconds.
+ * @returns The formatted time string.
+ */
+export declare const formatTime: (seconds: number) => string;
+/**
+ * Converts milliseconds to a human-readable time format.
+ *
+ * @param ms - The number of milliseconds.
+ * @returns A formatted string (e.g., "2h 15m 30s").
+ */
+export declare const formatDuration: (ms: number) => string;

package/dist/runtime/type.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Determines whether a value is a primitive.
+ *
+ * A primitive is defined here as one of:
+ * string, number, boolean, bigint, symbol, undefined, or null.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is primitive, false otherwise.
+ */
+export declare const isPrimitive: (value: unknown) => value is string | number | boolean | bigint | symbol | null | undefined;
+/**
+ * Determines whether a value is a plain object.
+ *
+ * A plain object is an object whose constructor is Object.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export declare const isObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Determines whether a value is an array.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is an array, false otherwise.
+ */
+export declare const isArray: <T>(value: unknown) => value is T[];
+/**
+ * Checks if a value is empty.
+ *
+ * For arrays and strings, it checks if the length is 0.
+ * For plain objects, it checks if there are no enumerable keys.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is empty, false otherwise.
+ */
+export declare const isEmpty: (value: unknown) => boolean;

package/dist/runtime/url.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Parses the query parameters from a URL string into an object.
+ *
+ * @param urlString - The URL string to parse.
+ * @returns An object where keys are query parameter names and values are query parameter values.
+ *
+ * @example
+ * // returns { search: 'test', page: '2' }
+ * getQueryParams('https://example.com/?search=test&page=2');
+ */
+export declare const getQueryParams: (urlString: string) => Record<string, string>;
+/**
+ * Updates (or adds) a query parameter in a given URL string.
+ *
+ * @param urlString - The original URL string.
+ * @param key - The query parameter key to update.
+ * @param value - The new value for the query parameter.
+ * @returns The updated URL string.
+ *
+ * @example
+ * // returns 'https://example.com/?search=new'
+ * updateQueryParam('https://example.com/?search=test', 'search', 'new');
+ */
+export declare const updateQueryParam: (urlString: string, key: string, value: string) => string;
+/**
+ * Removes a query parameter from a given URL string.
+ *
+ * @param urlString - The original URL string.
+ * @param key - The query parameter key to remove.
+ * @returns The updated URL string with the specified query parameter removed.
+ *
+ * @example
+ * // returns 'https://example.com/'
+ * removeQueryParam('https://example.com/?search=test', 'search');
+ */
+export declare const removeQueryParam: (urlString: string, key: string) => string;
+/**
+ * Builds a URL from a base URL, an optional path, and optional query parameters.
+ *
+ * @param baseUrl - The base URL (e.g., "https://example.com").
+ * @param path - Optional path to append to the base URL (e.g., "/api/v1/resource").
+ * @param queryParams - Optional object representing query parameters, where keys are parameter names and values are parameter values.
+ * @returns The constructed URL as a string.
+ *
+ * @example
+ * // returns 'https://example.com/api/v1/resource?search=test&page=2'
+ * buildUrl('https://example.com', '/api/v1/resource', { search: 'test', page: 2 });
+ */
+export declare const buildUrl: (baseUrl: string, path?: string, queryParams?: Record<string, string | number | boolean>) => string;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@germondai/ts-utils",
+  "version": "0.0.1",
+  "description": "Germond's TypeScript Utilities",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/germondai/ts-utils.git"
+  },
+  "author": "germondai",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js",
+      "require": "./dist/module.js"
+    }
+  },
+  "main": "./dist/module.js",
+  "types": "./dist/module.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "bun run build",
+    "build": "bun build --target=node ./src/module.ts --outfile=dist/module.js && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --project tsconfig.types.json",
+    "release": "bun fmt && bun prepack && changelogen --release && bun publish && git push --follow-tags",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write --list-different .",
+    "fmt": "bun prettier:fix"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.5.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.7.3"
+  }
+}