@tempots/std 0.20.0 → 0.21.0

package/url.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Utilities for working with URLs and paths.
+ *
+ * This module provides comprehensive URL manipulation, query parameter handling,
+ * and path utilities. Functions are designed to work safely with both absolute
+ * and relative URLs, and handle edge cases gracefully.
+ *
+ * @public
+ */
+/**
+ * Safely parses a URL string into a URL object.
+ *
+ * This function provides better error handling than the URL constructor
+ * by returning null for invalid URLs instead of throwing.
+ *
+ * @example
+ * ```typescript
+ * const url = parseUrl('https://example.com/path?param=value')
+ * // Result: URL object
+ *
+ * const invalid = parseUrl('not-a-url')
+ * // Result: null
+ * ```
+ *
+ * @param url - The URL string to parse
+ * @returns A URL object if valid, null otherwise
+ * @public
+ */
+export declare const parseUrl: (url: string) => URL | null;
+/**
+ * Builds a URL from a base URL and query parameters.
+ *
+ * This function safely constructs URLs with query parameters,
+ * handling encoding and existing parameters properly.
+ *
+ * @example
+ * ```typescript
+ * const url = buildUrl('https://api.example.com/users', {
+ *   page: '1',
+ *   limit: '10',
+ *   search: 'john doe'
+ * })
+ * // Result: 'https://api.example.com/users?page=1&limit=10&search=john%20doe'
+ * ```
+ *
+ * @param base - The base URL
+ * @param params - Query parameters to add
+ * @returns The constructed URL string
+ * @public
+ */
+export declare const buildUrl: (base: string, params?: Record<string, string>) => string;
+/**
+ * Extracts query parameters from a URL as an object.
+ *
+ * This function parses the query string and returns all parameters
+ * as a plain object with string values.
+ *
+ * @example
+ * ```typescript
+ * const params = getQueryParams('https://example.com/path?name=john&age=30&active=true')
+ * // Result: { name: 'john', age: '30', active: 'true' }
+ *
+ * const empty = getQueryParams('https://example.com/path')
+ * // Result: {}
+ * ```
+ *
+ * @param url - The URL to extract parameters from
+ * @returns An object containing all query parameters
+ * @public
+ */
+export declare const getQueryParams: (url: string) => Record<string, string>;
+/**
+ * Sets a query parameter in a URL.
+ *
+ * This function adds or updates a single query parameter in a URL,
+ * preserving all other parameters and URL components.
+ *
+ * @example
+ * ```typescript
+ * const url = setQueryParam('https://example.com/path?existing=value', 'new', 'param')
+ * // Result: 'https://example.com/path?existing=value&new=param'
+ *
+ * const updated = setQueryParam('https://example.com/path?existing=old', 'existing', 'new')
+ * // Result: 'https://example.com/path?existing=new'
+ * ```
+ *
+ * @param url - The base URL
+ * @param key - The parameter key
+ * @param value - The parameter value
+ * @returns The URL with the parameter set
+ * @public
+ */
+export declare const setQueryParam: (url: string, key: string, value: string) => string;
+/**
+ * Removes a query parameter from a URL.
+ *
+ * This function removes a specific query parameter from a URL,
+ * preserving all other parameters and URL components.
+ *
+ * @example
+ * ```typescript
+ * const url = removeQueryParam('https://example.com/path?keep=this&remove=that', 'remove')
+ * // Result: 'https://example.com/path?keep=this'
+ * ```
+ *
+ * @param url - The base URL
+ * @param key - The parameter key to remove
+ * @returns The URL with the parameter removed
+ * @public
+ */
+export declare const removeQueryParam: (url: string, key: string) => string;
+/**
+ * Checks if a string is a valid URL.
+ *
+ * This function validates URLs more safely than using the URL constructor
+ * directly, as it doesn't throw exceptions.
+ *
+ * @example
+ * ```typescript
+ * isValidUrl('https://example.com') // true
+ * isValidUrl('http://localhost:3000/path') // true
+ * isValidUrl('ftp://files.example.com') // true
+ * isValidUrl('not-a-url') // false
+ * isValidUrl('') // false
+ * ```
+ *
+ * @param url - The string to validate
+ * @returns true if the string is a valid URL, false otherwise
+ * @public
+ */
+export declare const isValidUrl: (url: string) => boolean;
+/**
+ * Joins multiple path segments into a single path.
+ *
+ * This function properly handles leading and trailing slashes,
+ * ensuring a clean path without double slashes or missing separators.
+ *
+ * @example
+ * ```typescript
+ * const path = joinPaths('api', 'v1', 'users', '123')
+ * // Result: 'api/v1/users/123'
+ *
+ * const withSlashes = joinPaths('/api/', '/v1/', 'users/')
+ * // Result: '/api/v1/users/'
+ *
+ * const empty = joinPaths('', 'path', '', 'file')
+ * // Result: 'path/file'
+ * ```
+ *
+ * @param paths - Path segments to join
+ * @returns The joined path
+ * @public
+ */
+export declare const joinPaths: (...paths: string[]) => string;
+/**
+ * Normalizes a path by removing redundant segments.
+ *
+ * This function resolves '..' and '.' segments in paths,
+ * similar to path.normalize in Node.js but for web contexts.
+ *
+ * @example
+ * ```typescript
+ * const path = normalizePath('/api/../users/./123/../456')
+ * // Result: '/users/456'
+ *
+ * const relative = normalizePath('../../parent/child')
+ * // Result: '../../parent/child'
+ * ```
+ *
+ * @param path - The path to normalize
+ * @returns The normalized path
+ * @public
+ */
+export declare const normalizePath: (path: string) => string;
+/**
+ * Extracts the file extension from a path.
+ *
+ * This function returns the file extension including the dot,
+ * or an empty string if no extension is found.
+ *
+ * @example
+ * ```typescript
+ * getFileExtension('/path/to/file.txt') // '.txt'
+ * getFileExtension('image.jpeg') // '.jpeg'
+ * getFileExtension('README') // ''
+ * getFileExtension('.hidden') // ''
+ * getFileExtension('file.tar.gz') // '.gz'
+ * ```
+ *
+ * @param path - The path to extract extension from
+ * @returns The file extension including the dot, or empty string
+ * @public
+ */
+export declare const getFileExtension: (path: string) => string;
+/**
+ * Extracts the file name from a path.
+ *
+ * This function returns the last segment of a path,
+ * which is typically the file name.
+ *
+ * @example
+ * ```typescript
+ * getFileName('/path/to/file.txt') // 'file.txt'
+ * getFileName('file.txt') // 'file.txt'
+ * getFileName('/path/to/directory/') // ''
+ * getFileName('/path/to/directory') // 'directory'
+ * ```
+ *
+ * @param path - The path to extract file name from
+ * @returns The file name
+ * @public
+ */
+export declare const getFileName: (path: string) => string;
+/**
+ * Extracts the base name (file name without extension) from a path.
+ *
+ * This function returns the file name without its extension.
+ *
+ * @example
+ * ```typescript
+ * getBaseName('/path/to/file.txt') // 'file'
+ * getBaseName('image.jpeg') // 'image'
+ * getBaseName('README') // 'README'
+ * getBaseName('.hidden') // '.hidden'
+ * getBaseName('file.tar.gz') // 'file.tar'
+ * ```
+ *
+ * @param path - The path to extract base name from
+ * @returns The base name without extension
+ * @public
+ */
+export declare const getBaseName: (path: string) => string;

package/url.js

@@ -0,0 +1,79 @@
+const a = (t) => {
+  try {
+    return new URL(t);
+  } catch {
+    return null;
+  }
+}, u = (t, e) => {
+  if (!e || Object.keys(e).length === 0)
+    return t;
+  const n = new URL(t);
+  for (const [r, s] of Object.entries(e))
+    n.searchParams.set(r, s);
+  return n.toString();
+}, h = (t) => {
+  try {
+    const e = new URL(t), n = {};
+    for (const [r, s] of e.searchParams)
+      n[r] = s;
+    return n;
+  } catch {
+    return {};
+  }
+}, f = (t, e, n) => {
+  try {
+    const r = new URL(t);
+    return r.searchParams.set(e, n), r.toString();
+  } catch {
+    return t;
+  }
+}, g = (t, e) => {
+  try {
+    const n = new URL(t);
+    return n.searchParams.delete(e), n.toString();
+  } catch {
+    return t;
+  }
+}, m = (t) => {
+  try {
+    return new URL(t), !0;
+  } catch {
+    return !1;
+  }
+}, y = (...t) => {
+  if (t.length === 0) return "";
+  const e = t.filter((c) => c.length > 0);
+  if (e.length === 0) return "";
+  const n = e[0].startsWith("/"), r = e[e.length - 1].endsWith("/"), o = e.map((c) => c.replace(/^\/+|\/+$/g, "")).filter((c) => c.length > 0).join("/");
+  return (n ? "/" : "") + o + (r ? "/" : "");
+}, P = (t) => {
+  if (!t) return "";
+  const e = t.startsWith("/"), n = t.split("/").filter((o) => o.length > 0), r = [];
+  for (const o of n)
+    o !== "." && (o === ".." ? r.length > 0 && r[r.length - 1] !== ".." ? r.pop() : e || r.push("..") : r.push(o));
+  const s = r.join("/");
+  return e ? "/" + s : s;
+}, i = (t) => {
+  const e = l(t), n = e.lastIndexOf(".");
+  return n === -1 || n === 0 ? "" : e.substring(n);
+}, l = (t) => {
+  if (!t || t.match(/\/+$/)) return "";
+  const e = t.lastIndexOf("/");
+  return e === -1 ? t : t.substring(e + 1);
+}, d = (t) => {
+  const e = l(t), n = i(t);
+  return n ? e.substring(0, e.length - n.length) : e;
+};
+export {
+  u as buildUrl,
+  d as getBaseName,
+  i as getFileExtension,
+  l as getFileName,
+  h as getQueryParams,
+  m as isValidUrl,
+  y as joinPaths,
+  P as normalizePath,
+  a as parseUrl,
+  g as removeQueryParam,
+  f as setQueryParam
+};