@catbee/utils 0.0.8-rc.3 → 1.0.1

package/build/esm/utils/type.utils.js

@@ -1,186 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-/**
- * Check if a value is of a specific primitive type.
- *
- * @param value - Value to check
- * @param type - Type to check against
- * @returns Whether the value is of the specified type
- *
- * @example
- * ```typescript
- * isPrimitiveType('hello', 'string'); // true
- * isPrimitiveType(42, 'number'); // true
- * isPrimitiveType(true, 'boolean'); // true
- * isPrimitiveType(null, 'null'); // true
- * isPrimitiveType(undefined, 'undefined'); // true
- * isPrimitiveType({}, 'object'); // true
- * isPrimitiveType([], 'array'); // true
- * ```
- */
-export function isPrimitiveType(value, type) {
-    if (type === 'array') {
-        return Array.isArray(value);
-    }
-    if (type === 'null') {
-        return value === null;
-    }
-    if (type === 'undefined') {
-        return value === undefined;
-    }
-    if (type === 'object') {
-        // Only plain objects, not arrays or null
-        return typeof value === 'object' && value !== null && !Array.isArray(value);
-    }
-    return typeof value === type;
-}
-/**
- * Get the primitive type of a value as a string.
- *
- * @param value - Value to get the type of
- * @returns String representing the type
- *
- * @example
- * ```typescript
- * getTypeOf('hello'); // 'string'
- * getTypeOf(42); // 'number'
- * getTypeOf([]); // 'array'
- * getTypeOf(null); // 'null'
- * ```
- */
-export function getTypeOf(value) {
-    if (value === null)
-        return 'null';
-    if (value === undefined)
-        return 'undefined';
-    if (Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
-/**
- * Type guard for checking if a value is an array of a specific type.
- *
- * @param value - Value to check
- * @param itemTypeGuard - Function that checks if items are of the expected type
- * @returns True if the value is an array with items of the expected type
- *
- * @example
- * ```typescript
- * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true
- * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true
- * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false
- * ```
- */
-export function isArrayOf(value, itemTypeGuard) {
-    if (!Array.isArray(value))
-        return false;
-    return value.every(item => itemTypeGuard(item));
-}
-/**
- * Convert a value to a string.
- *
- * @param value - Value to convert
- * @param defaultValue - Default value if conversion fails
- * @returns String representation of the value
- */
-export function toStr(value, defaultValue = '') {
-    if (value === null || value === undefined)
-        return defaultValue;
-    try {
-        if (typeof value === 'object') {
-            return JSON.stringify(value);
-        }
-        return String(value);
-    }
-    catch {
-        return defaultValue;
-    }
-}
-/**
- * Convert a value to a number.
- *
- * @param value - Value to convert
- * @param defaultValue - Default value if conversion fails
- * @returns Numeric representation of the value
- */
-export function toNum(value, defaultValue = 0) {
-    if (value === null || value === undefined)
-        return defaultValue;
-    if (typeof value === 'number')
-        return value;
-    try {
-        const num = Number(value);
-        return isNaN(num) ? defaultValue : num;
-    }
-    catch {
-        return defaultValue;
-    }
-}
-/**
- * Convert a value to a boolean.
- *
- * @param value - Value to convert
- * @param defaultValue - Default value if conversion fails
- * @returns Boolean representation of the value
- */
-export function toBool(value, defaultValue = false) {
-    if (value === null || value === undefined)
-        return defaultValue;
-    if (typeof value === 'boolean')
-        return value;
-    if (typeof value === 'string') {
-        const lowercased = value.toLowerCase();
-        if (lowercased === 'true' || lowercased === 'yes' || lowercased === 'y' || lowercased === '1') {
-            return true;
-        }
-        if (lowercased === 'false' || lowercased === 'no' || lowercased === 'n' || lowercased === '0') {
-            return false;
-        }
-    }
-    if (typeof value === 'number') {
-        return value !== 0;
-    }
-    return defaultValue;
-}
-/**
- * Ensure a value matches the expected type, or provide a default.
- *
- * @param value - Value to check
- * @param expectedType - Expected primitive type
- * @param defaultValue - Default value to use if type doesn't match
- * @returns The value if it matches the type, otherwise the default
- *
- * @example
- * ```typescript
- * ensureType(42, 'number', 0); // 42
- * ensureType('42', 'number', 0); // 0
- * ensureType(undefined, 'string', 'default'); // 'default'
- * ```
- */
-export function ensureType(value, expectedType, defaultValue) {
-    if (getTypeOf(value) === expectedType) {
-        return value;
-    }
-    return defaultValue;
-}

package/build/esm/utils/url.utils.d.ts

@@ -1,140 +0,0 @@
-/**
- * Appends query parameters to a given URL.
- *
- * @param {string} url - The base URL to which query parameters will be appended.
- * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
- * @returns {string} The new URL string with query parameters appended.
- *
- * @example
- * appendQueryParams('https://example.com', { page: 1, limit: 10 });
- * // → 'https://example.com/?page=1&limit=10'
- */
-export declare function appendQueryParams(url: string, params: Record<string, string | number>): string;
-/**
- * Parses a query string into a key-value object.
- *
- * @param {string} query - The query string (with or without leading '?').
- * @returns {Record<string, string>} Object representing parsed query parameters.
- *
- * @example
- * parseQueryString('?page=1&limit=10');
- * // → { page: '1', limit: '10' }
- */
-export declare function parseQueryString(query: string): Record<string, string>;
-/**
- * Validates if a string is a valid URL.
- *
- * @param {string} url - The URL string to validate.
- * @param {boolean} [requireHttps=false] - If true, requires the URL to use HTTPS.
- * @returns {boolean} True if the URL is valid, false otherwise.
- */
-export declare function isValidUrl(url: string, requireHttps?: boolean): boolean;
-/**
- * Extracts the domain name from a URL.
- *
- * @param {string} url - The URL to extract the domain from.
- * @param {boolean} [removeSubdomains=false] - If true, removes subdomains (returns root domain only).
- * @returns {string} The domain name.
- *
- * @example
- * getDomain('https://api.example.com/path');
- * // → 'api.example.com'
- *
- * getDomain('https://api.example.com/path', true);
- * // → 'example.com'
- */
-export declare function getDomain(url: string, removeSubdomains?: boolean): string;
-/**
- * Joins URL paths properly handling slashes.
- *
- * @param {...string[]} segments - URL path segments to join.
- * @returns {string} Joined URL path.
- *
- * @example
- * joinPaths('https://example.com/', '/api/', '/users');
- * // → 'https://example.com/api/users'
- */
-export declare function joinPaths(...segments: string[]): string;
-/**
- * Normalizes a URL by resolving relative paths, handling protocol-relative URLs, etc.
- *
- * @param {string} url - The URL to normalize.
- * @param {string} [base] - Optional base URL for resolving relative URLs.
- * @returns {string} Normalized URL.
- *
- * @example
- * normalizeUrl('HTTP://Example.COM/foo/../bar');
- * // → 'http://example.com/bar'
- */
-export declare function normalizeUrl(url: string, base?: string): string;
-/**
- * Creates a URL builder for constructing URLs with a base URL.
- *
- * @param {string} baseUrl - The base URL to build upon.
- * @returns {Object} URL builder methods.
- *
- * @example
- * const api = createUrlBuilder('https://api.example.com');
- * api.path('/users', { active: true });
- * // → 'https://api.example.com/users?active=true'
- */
-export declare function createUrlBuilder(baseUrl: string): {
-    /**
-     * Creates a full URL with the given path and query parameters.
-     *
-     * @param {string} path - The path to append to the base URL.
-     * @param {Record<string, any>} [params] - Query parameters to add.
-     * @returns {string} The complete URL.
-     */
-    path(path: string, params?: Record<string, any>): string;
-    /**
-     * Creates a full URL with query parameters but no additional path.
-     *
-     * @param {Record<string, any>} params - Query parameters to add.
-     * @returns {string} The complete URL with query parameters.
-     */
-    query(params: Record<string, any>): string;
-};
-/**
- * Extracts specific query parameters from a URL.
- *
- * @param {string} url - The URL to extract parameters from.
- * @param {string[]} paramNames - Names of parameters to extract.
- * @returns {Record<string, string>} Object containing the extracted parameters.
- */
-export declare function extractQueryParams(url: string, paramNames: string[]): Record<string, string>;
-/**
- * Removes specified query parameters from a URL.
- *
- * @param {string} url - The URL to modify.
- * @param {string[]} paramsToRemove - Names of parameters to remove.
- * @returns {string} URL with parameters removed.
- */
-export declare function removeQueryParams(url: string, paramsToRemove: string[]): string;
-/**
- * Gets the file extension from a URL path.
- *
- * @param {string} url - The URL to examine.
- * @returns {string} The file extension (without dot) or empty string if none found.
- *
- * @example
- * getExtension('https://example.com/document.pdf?v=1');
- * // → 'pdf'
- */
-export declare function getExtension(url: string): string;
-/**
- * Parses URL query parameters into a strongly-typed object.
- *
- * @template T Expected type of the query parameters
- * @param {string} url - The URL to parse.
- * @param {Record<keyof T, (val: string) => any>} [converters] - Type converters for params.
- * @returns {Partial<T>} Typed query parameters.
- *
- * @example
- * parseTypedQueryParams<{page: number, q: string}>('https://example.com?page=2&q=test', {
- *   page: Number,
- *   q: String
- * });
- * // → { page: 2, q: 'test' }
- */
-export declare function parseTypedQueryParams<T extends Record<string, any>>(url: string, converters?: Record<keyof T, (val: string) => any>): Partial<T>;

package/build/esm/utils/url.utils.js

@@ -1,303 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-import { URL, URLSearchParams } from 'url';
-/**
- * Appends query parameters to a given URL.
- *
- * @param {string} url - The base URL to which query parameters will be appended.
- * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
- * @returns {string} The new URL string with query parameters appended.
- *
- * @example
- * appendQueryParams('https://example.com', { page: 1, limit: 10 });
- * // → 'https://example.com/?page=1&limit=10'
- */
-export function appendQueryParams(url, params) {
-    const urlObj = new URL(url);
-    for (const [key, value] of Object.entries(params)) {
-        urlObj.searchParams.set(key, value.toString());
-    }
-    return urlObj.toString();
-}
-/**
- * Parses a query string into a key-value object.
- *
- * @param {string} query - The query string (with or without leading '?').
- * @returns {Record<string, string>} Object representing parsed query parameters.
- *
- * @example
- * parseQueryString('?page=1&limit=10');
- * // → { page: '1', limit: '10' }
- */
-export function parseQueryString(query) {
-    const cleanQuery = query.startsWith('?') ? query.slice(1) : query;
-    // Object.fromEntries guarantees string values in result
-    return Object.fromEntries(new URLSearchParams(cleanQuery));
-}
-/**
- * Validates if a string is a valid URL.
- *
- * @param {string} url - The URL string to validate.
- * @param {boolean} [requireHttps=false] - If true, requires the URL to use HTTPS.
- * @returns {boolean} True if the URL is valid, false otherwise.
- */
-export function isValidUrl(url, requireHttps = false) {
-    try {
-        const parsedUrl = new URL(url);
-        if (!parsedUrl.protocol || !parsedUrl.hostname)
-            return false;
-        if (requireHttps && parsedUrl.protocol !== 'https:')
-            return false;
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Extracts the domain name from a URL.
- *
- * @param {string} url - The URL to extract the domain from.
- * @param {boolean} [removeSubdomains=false] - If true, removes subdomains (returns root domain only).
- * @returns {string} The domain name.
- *
- * @example
- * getDomain('https://api.example.com/path');
- * // → 'api.example.com'
- *
- * getDomain('https://api.example.com/path', true);
- * // → 'example.com'
- */
-export function getDomain(url, removeSubdomains = false) {
-    try {
-        const { hostname } = new URL(url);
-        if (!removeSubdomains) {
-            return hostname;
-        }
-        // Extract root domain (remove subdomains)
-        const parts = hostname.split('.');
-        if (parts.length <= 2)
-            return hostname;
-        // Handle special cases like co.in, com.au
-        const secondLevelDomains = ['co', 'com', 'org', 'net', 'gov', 'edu', 'ac'];
-        const sld = parts[parts.length - 2];
-        if (secondLevelDomains.includes(sld) && parts.length > 2) {
-            return parts.slice(-3).join('.');
-        }
-        return parts.slice(-2).join('.');
-    }
-    catch {
-        return '';
-    }
-}
-/**
- * Joins URL paths properly handling slashes.
- *
- * @param {...string[]} segments - URL path segments to join.
- * @returns {string} Joined URL path.
- *
- * @example
- * joinPaths('https://example.com/', '/api/', '/users');
- * // → 'https://example.com/api/users'
- */
-export function joinPaths(...segments) {
-    let result = segments
-        .filter(s => s !== undefined && s !== null)
-        .map((segment, index) => {
-        if (index === 0)
-            return segment.replace(/\/+$/, '');
-        return segment.replace(/^\/+|\/+$/g, '');
-    })
-        .filter(Boolean)
-        .join('/');
-    if (segments[0] === '' && !result.startsWith('/'))
-        result = '/' + result;
-    return result;
-}
-/**
- * Normalizes a URL by resolving relative paths, handling protocol-relative URLs, etc.
- *
- * @param {string} url - The URL to normalize.
- * @param {string} [base] - Optional base URL for resolving relative URLs.
- * @returns {string} Normalized URL.
- *
- * @example
- * normalizeUrl('HTTP://Example.COM/foo/../bar');
- * // → 'http://example.com/bar'
- */
-export function normalizeUrl(url, base) {
-    try {
-        // Handle protocol-relative URLs
-        if (url.startsWith('//')) {
-            url = `https:${url}`;
-        }
-        // Resolve relative URLs against a base
-        const parsedUrl = base ? new URL(url, base) : new URL(url);
-        // Normalize
-        parsedUrl.pathname = parsedUrl.pathname.replace(/\/+/g, '/'); // Collapse multiple slashes
-        parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, ''); // Remove trailing slash
-        parsedUrl.hostname = parsedUrl.hostname.toLowerCase();
-        return parsedUrl.toString();
-    }
-    catch {
-        return url; // Return original if invalid
-    }
-}
-/**
- * Creates a URL builder for constructing URLs with a base URL.
- *
- * @param {string} baseUrl - The base URL to build upon.
- * @returns {Object} URL builder methods.
- *
- * @example
- * const api = createUrlBuilder('https://api.example.com');
- * api.path('/users', { active: true });
- * // → 'https://api.example.com/users?active=true'
- */
-export function createUrlBuilder(baseUrl) {
-    return {
-        /**
-         * Creates a full URL with the given path and query parameters.
-         *
-         * @param {string} path - The path to append to the base URL.
-         * @param {Record<string, any>} [params] - Query parameters to add.
-         * @returns {string} The complete URL.
-         */
-        path(path, params) {
-            const url = joinPaths(baseUrl, path);
-            return params ? appendQueryParams(url, params) : url;
-        },
-        /**
-         * Creates a full URL with query parameters but no additional path.
-         *
-         * @param {Record<string, any>} params - Query parameters to add.
-         * @returns {string} The complete URL with query parameters.
-         */
-        query(params) {
-            return appendQueryParams(baseUrl, params);
-        }
-    };
-}
-/**
- * Extracts specific query parameters from a URL.
- *
- * @param {string} url - The URL to extract parameters from.
- * @param {string[]} paramNames - Names of parameters to extract.
- * @returns {Record<string, string>} Object containing the extracted parameters.
- */
-export function extractQueryParams(url, paramNames) {
-    try {
-        const parsedUrl = new URL(url);
-        const result = {};
-        for (const name of paramNames) {
-            const value = parsedUrl.searchParams.get(name);
-            if (value !== null) {
-                result[name] = value;
-            }
-        }
-        return result;
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Removes specified query parameters from a URL.
- *
- * @param {string} url - The URL to modify.
- * @param {string[]} paramsToRemove - Names of parameters to remove.
- * @returns {string} URL with parameters removed.
- */
-export function removeQueryParams(url, paramsToRemove) {
-    try {
-        const parsedUrl = new URL(url);
-        for (const param of paramsToRemove) {
-            parsedUrl.searchParams.delete(param);
-        }
-        return parsedUrl.toString();
-    }
-    catch {
-        return url;
-    }
-}
-/**
- * Gets the file extension from a URL path.
- *
- * @param {string} url - The URL to examine.
- * @returns {string} The file extension (without dot) or empty string if none found.
- *
- * @example
- * getExtension('https://example.com/document.pdf?v=1');
- * // → 'pdf'
- */
-export function getExtension(url) {
-    try {
-        const { pathname } = new URL(url);
-        const match = pathname.match(/\.([^./\\?#]+)$/);
-        return match ? match[1].toLowerCase() : '';
-    }
-    catch {
-        // If URL parsing fails, try a simpler approach
-        const match = url.match(/\.([^./\\?#]+)$/);
-        return match ? match[1].toLowerCase() : '';
-    }
-}
-/**
- * Parses URL query parameters into a strongly-typed object.
- *
- * @template T Expected type of the query parameters
- * @param {string} url - The URL to parse.
- * @param {Record<keyof T, (val: string) => any>} [converters] - Type converters for params.
- * @returns {Partial<T>} Typed query parameters.
- *
- * @example
- * parseTypedQueryParams<{page: number, q: string}>('https://example.com?page=2&q=test', {
- *   page: Number,
- *   q: String
- * });
- * // → { page: 2, q: 'test' }
- */
-export function parseTypedQueryParams(url, converters) {
-    try {
-        const { searchParams } = new URL(url);
-        const result = {};
-        for (const [key, value] of searchParams.entries()) {
-            if (converters && key in converters) {
-                try {
-                    result[key] = converters[key](value);
-                }
-                catch {
-                    // Skip on conversion error
-                }
-            }
-            else {
-                result[key] = value;
-            }
-        }
-        return result;
-    }
-    catch {
-        return {};
-    }
-}