@codady/utils 0.0.38 → 0.0.40

package/src/ajax.ts

@@ -0,0 +1,470 @@
+/**
+ * @since Last modified: 2026/01/20 18:14:18
+ * Sends an asynchronous HTTP request (AJAX).
+ * @function ajax
+ * @param {AjaxOptions} options - Configuration for the request.
+ * @returns {Promise<AjaxResponse>} Returns a promise that resolves with the response context.
+ * @example
+ * ajax({ url: '/api/data', method: 'GET' }).then(res => console.log(res.content));
+ */
+
+'use strict';
+
+import isEmpty from './isEmpty';
+import getDataType from './getDataType';
+import getBodyHTML from './getBodyHTML';
+import getUrlHash from './getUrlHash';
+import capitalize from './capitalize';
+import buildUrl from './buildUrl';
+import cleanQueryString from './cleanQueryString';
+
+/**
+ * Interface for the AJAX configuration options.
+ */
+interface AjaxOptions {
+    url: string;                            // Request URL
+    method?: string | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'TRACE';
+    async?: boolean;                        // Whether the request is asynchronous
+    data?: any;                             // Data to be sent
+    selector?: string;                      // Selector to extract specific content from HTML response
+    timeout?: number;                       // Request timeout in milliseconds
+    headers?: Record<string, string>;       // HTTP headers
+    responseType?: XMLHttpRequestResponseType; // Expected response type (json, blob, etc.)
+    catchError?: boolean;                   // Whether to reject the promise on error/timeout
+    signal?: AbortSignal;                   // AbortSignal for canceling the request
+    xhrFields?: Record<string, any>;        // Additional fields to set on the XHR object
+    cacheBustKey?: string,
+    precision?: number,
+    // Callbacks
+    onAbort?: ((resp: AjaxResponse) => void) | null;
+    onTimeout?: ((resp: AjaxResponse) => void) | null;
+    onOpened?: ((resp: AjaxResponse) => void) | null;
+    onHeadersReceived?: ((resp: AjaxResponse) => void) | null;
+    onLoading?: ((resp: AjaxResponse) => void) | null;
+    onBeforeSend?: ((resp: AjaxResponse) => void) | null;
+    onDownload?: ((resp: AjaxResponse) => void) | null;
+    onUpload?: ((resp: AjaxResponse) => void) | null;
+    onComplete?: ((resp: AjaxResponse) => void) | null; // Called when upload/download reaches 100%
+    onSuccess?: ((resp: AjaxResponse) => void) | null;
+    onFailure?: ((resp: AjaxResponse) => void) | null;
+    onInformation?: ((resp: AjaxResponse) => void) | null;
+    onRedirection?: ((resp: AjaxResponse) => void) | null;
+    onUnknownError?: ((resp: AjaxResponse) => void) | null;
+    onClientError?: ((resp: AjaxResponse) => void) | null;
+    onServerError?: ((resp: AjaxResponse) => void) | null;
+    onError?: ((resp: AjaxResponse) => void) | null;
+    onFinish?: ((resp: AjaxResponse) => void) | null;   // Called on both success and failure
+    onCreated?: ((resp: AjaxResponse) => void) | null;
+}
+
+/**
+ * Interface for the response object passed to callbacks.
+ */
+interface AjaxResponse {
+    xhr: XMLHttpRequest;
+    data: any;           // The processed data sent in the request
+    abort: () => void;   // Function to manually abort the request
+    status: number | string;
+    content: any;        // The response body (parsed JSON, DOM string, etc.)
+    stage: number;       // XHR readyState (0-4)
+    type: string;        // Current stage name (e.g., 'success', 'timeout')
+    progress: {
+        name?: 'upload' | 'download';
+        loaded?: number;
+        total?: number;
+        timestamp?: number;
+        ratio?: number;
+        percent?: number;
+        text?: string;
+    };
+}
+
+const ajax = (options: AjaxOptions) => {
+    // Validation
+    if (isEmpty(options)) {
+        return Promise.reject(new Error('Options are required'));
+    }
+
+    if (!options.url || typeof options.url !== 'string') {
+        return Promise.reject(new Error('URL is required and must be a string'));
+    }
+
+    // Default configuration
+    const config: Required<AjaxOptions> = {
+        url: '',
+        method: 'POST',
+        async: true,
+        selector: '',
+        data: null,
+        timeout: 3600000,
+        headers: {},
+        responseType: '',
+        catchError: false,
+        signal: null as any,
+        xhrFields: {},
+        cacheBustKey: '_t',
+        precision: 2,
+        //
+        onAbort: null,
+        onTimeout: null,
+        //
+        onBeforeSend: null,
+        //
+        onCreated: null,
+        onOpened: null,
+        onHeadersReceived: null,
+        onLoading: null,
+        //
+        onSuccess: null,
+        onFailure: null,
+        onInformation: null,
+        onRedirection: null,
+        onClientError: null,
+        onServerError: null,
+        onUnknownError: null,
+        onError: null,
+        onFinish: null,
+        //
+        onDownload: null,
+        onUpload: null,
+        onComplete: null,
+    };
+
+    //合并参数
+    Object.assign(config, options);
+
+    //
+    const method = config.method.toUpperCase() || 'POST',
+        methodsWithoutBody = ['GET', 'HEAD', 'TRACE'];
+
+    //创建XMLHttpRequest
+    let xhr: any = new XMLHttpRequest(),
+        //设置发送数据和预设请求头
+        requestData: any = null,
+        headerContentType = config?.headers?.['Content-Type'] || config?.headers?.['content-type'],
+        removeHeader = () => {
+            if (headerContentType) {
+                delete config.headers['Content-Type'];
+                delete config.headers['content-type'];
+            }
+        }
+    if (!isEmpty(config.data)) {
+
+        let dataType = getDataType(config.data)
+        if (dataType === 'FormData') {
+            //如果是new FormData格式，直接相等
+            requestData = config.data;
+            // 不需要手动设置Content-Type，浏览器会自动设置
+            //config.contType = 'multipart/form-data';
+            removeHeader();
+        } else if (dataType === 'Object') {
+            //如果是对象格式{name:'',age:''}
+            //并且此时已经设置了contType
+            if (!headerContentType) {
+                //如果未设置则默认设为如下contType
+                //Content-Type=application/x-www-form-urlencoded
+                /* for (let k in config.data) {
+                    requestData += '&' + k + '=' + config.data[k];
+                } */
+                requestData = new URLSearchParams(config.data).toString();
+                //URLSearchParams.toString => `a=1&b=3`
+                //非get、head方法修正content-type
+                if (!methodsWithoutBody.includes(method)) {
+                    config.headers['Content-Type'] = 'application/x-www-form-urlencoded';
+                }
+            } else if (headerContentType?.includes('application/json')) {
+                //Content-Type=application/json或contentType=application/json
+                requestData = JSON.stringify(config.data);
+            } else {
+                requestData = config.data;
+            }
+        } else if (dataType === 'String') {
+            //未设置或，已经设置了Content-Type=application/x-www-form-urlencoded
+            if (!headerContentType || headerContentType.includes('urlencoded')) {
+                //如果是name=''&age=''字符串
+                //?name=''&age=''或&name=''&age=''统一去掉第一个&/?
+                requestData = cleanQueryString(config.data.trim());
+                //非get、head方法修正content-type
+                if (!methodsWithoutBody.includes(method) && !headerContentType) {
+                    config.headers['Content-Type'] = 'application/x-www-form-urlencoded';
+                }
+            } else {
+                requestData = config.data;
+            }
+        } else {
+            requestData = config.data;
+        }
+    }
+
+    //设置超时时间
+    xhr.timeout = config.timeout;
+    // 响应类型
+    if (config.responseType) {
+        xhr.responseType = config.responseType as XMLHttpRequestResponseType;
+    }
+
+    //返回promise
+
+    const result = new Promise((resolve, reject) => {
+
+        //超时监听
+        const timeoutHandler = () => {
+            cleanup();
+            let resp = { ...context, status: xhr.status, content: xhr.response, type: 'timeout' };
+            //回调，status和content在此确认
+            config?.onTimeout?.(resp);
+            //reject只能接受一个参数
+            config.catchError ? reject(resp) : resolve(resp);
+            //超时也是不能获得数据的行为，定义为failure
+            config?.onFailure?.(resp);
+            //timeout会经过onreadystatechange，但是被及时的return了，所以这里多加一行
+            config?.onFinish?.(resp);
+        },
+            //报错监听
+            errorHandler = (resp: any) => {
+                //这几个错误来自xhr.onreadystatechange
+                if (resp.type === 'client-error') {
+                    config?.onClientError?.({ ...context });
+                } else if (resp.type === 'server-error') {
+                    config?.onServerError?.({ ...context });
+                } else if (resp.type === 'unknown-error') {
+                    config?.onUnknownError?.({ ...context });
+                }
+                //此外还会有xhr.onerror的错误，所以需要统一使用onError监听
+
+                config?.onError?.(resp);
+                //reject只能接受一个参数
+                config.catchError ? reject(resp) : resolve(resp);
+            },
+            //取消监听
+            abortHandler = () => {
+                cleanup();
+                const resp = { ...context, status: xhr.status, type: 'abort' }
+                config.catchError ? reject(resp) : resolve(resp);
+                //回调，status和content在此确认
+                config?.onAbort?.(resp);
+                //abort行为不会经过onreadystatechange，这里需要多这一行以表示xhr的完成（结束）
+                 config?.onFinish?.(resp);
+            },
+            abortHandlerWithSignal = () => {
+                //先中止请求，防止触发其他 readystate 事件
+                xhr.abort();
+                abortHandler();
+            },
+            //成功监听
+            successHandler = (resp: any) => {
+                //成功回调
+                config?.onSuccess?.(resp);
+                //resolve只能接受一个参数
+                resolve(resp);
+            },
+            //统一处理abort
+            cleanup = () => {
+                // 如果使用了AbortSignal，则移除它的事件监听器
+                config.signal && config.signal.removeEventListener('abort', abortHandlerWithSignal);
+                // 移除各类事件监听器
+                config.onError && xhr.removeEventListener('error', errorHandler);
+                config.onTimeout && xhr.removeEventListener('timeout', timeoutHandler);
+                // 解绑上传/下载进度事件
+                config.onUpload && xhr.upload.removeEventListener('progress', uploadProgressHandler);
+                config.onDownload && xhr.removeEventListener('progress', downloadProgressHandler);
+                //销毁
+                xhr.onreadystatechange = null;
+            },
+            // Context object to track state
+            context: AjaxResponse = {
+                //原始xhr
+                xhr,
+                //发送的数据
+                data: requestData,
+                //可取消的函数
+                abort: abortHandler,
+                //xhr.status
+                status: '',
+                //响应的内容
+                content: null,
+                //0~4阶段编号
+                stage: 0,
+                //阶段名称
+                type: 'unset',
+                //上传和下载进度
+                progress: {}
+            },
+            getProgressValues = (ratio: number) => {
+                let text = (ratio * 100).toFixed(config.precision);
+                return { percent: parseFloat(text), text }
+            },
+            //定义进度函数
+            progressHandler = (name: 'upload' | 'download', data: any, callback: Function) => {
+                if (data.lengthComputable) {
+                    const resp = { ...context, status: xhr.status },
+                        ratio = data.loaded / data.total,
+                        { percent, text } = getProgressValues(ratio);
+                    resp.progress = {
+                        name,
+                        loaded: data.loaded,
+                        total: data.total,
+                        timestamp: (new Date(data.timeStamp)).getTime(),
+                        ratio,
+                        percent,
+                        text,
+                    }
+                    callback?.(resp);
+                    if (ratio >= 1) {
+                        Object.assign(resp.progress, getProgressValues(1));
+                        config?.onComplete?.(resp);
+                    }
+
+                }
+            }, uploadProgressHandler = (data: any) => {
+                progressHandler('upload', data, (resp: any) => (config.onUpload as Function)(resp));
+            },
+            downloadProgressHandler = (data: any) => {
+                progressHandler('download', data, (resp: any) => (config.onDownload as Function)(resp));
+            };
+
+
+        //使用AbortSignal
+        if (config.signal) {
+            if (config.signal.aborted) return abortHandlerWithSignal();
+            config.signal.addEventListener('abort', abortHandlerWithSignal);
+        }
+
+        //监听上传进度
+        config.onUpload && xhr.upload.addEventListener('progress', uploadProgressHandler);
+
+        //监听下载进度
+        config.onDownload && xhr.addEventListener('progress', downloadProgressHandler);
+
+        // 事件监听器
+        config.onError && xhr.addEventListener('error', errorHandler);
+        config.onTimeout && xhr.addEventListener('timeout', timeoutHandler);
+        config.onAbort && xhr.addEventListener('abort', abortHandler);
+
+        // 手动触发 Created 状态
+        config.onCreated?.({ ...context, type: 'created' });
+
+        //状态判断
+        xhr.onreadystatechange = function () {
+            context.stage = xhr.readyState;
+            context.status = xhr.status;
+            const statusMap: Record<number, string> = { 1: 'opened', 2: 'headersReceived', 3: 'loading' };
+            //0=created放在外侧确保能触发，如果放在.onreadystatechange可能触发不了
+            if (xhr.readyState < 4) {
+                if (!xhr.readyState) return;
+                context.type = statusMap[xhr.readyState];
+                (config as any)[`on${capitalize(context.type)}`]?.({ ...context });
+                return;
+            }
+
+            //tiemeout事件也会执行这里，此时需要让它触发onTimeout事件
+            //abort和timeout行为的status是0
+            //不过abort行为不会执行到这里
+            if (xhr.status === 0 && context.type !== 'abort') {
+                return;
+            }
+
+            //已经请求成功，不会有timeout事件，也不需要abort了，所以移除abort事件
+            cleanup();
+
+            //根据状态码判断响应结果
+            const isInformation = xhr.status >= 100 && xhr.status < 200,
+                isSuccess = (xhr.status >= 200 && xhr.status < 300) || xhr.status === 304,
+                isRedirection = xhr.status >= 300 && xhr.status < 400,
+                isClientError = xhr.status >= 400 && xhr.status < 500,
+                isServerError = xhr.status >= 500 && xhr.status < 600;
+
+            //已经获得返回数据
+            if (isSuccess) {
+                if (!config.responseType || xhr.responseType === 'text') {
+                    //可能返回字符串类型的对象，wordpress的REST API
+                    let trim = xhr.responseText.trim(),
+                        content = '';
+                    if ((trim.startsWith('[') && trim.endsWith(']')) || (trim.startsWith('{') && trim.endsWith('}'))) {
+                        //通过判断开头字符是{或[来确定异步页面是否是JSON内容，如果是则转成JSON对象
+                        try {
+                            content = JSON.parse(trim);
+                        } catch {
+                            console.warn('Malformed JSON detected, falling back to text.');
+                            content = xhr.responseText;
+                        }
+                    } else if (/(<\/html>|<\/body>)/i.test(trim)) {
+                        //请求了一个HTML页面
+                        //返回文本类型DOMstring
+                        let urlHash = getUrlHash(config.url);
+                        content = getBodyHTML(trim, config.selector || urlHash);
+                    } else {
+                        //普通文本，不做任何处理
+                        content = xhr.responseText;
+                    }
+                    //content=文本字符串/json
+                    context.content = content;
+                } else {
+                    //content=json、blob、document、arraybuffer等类型，如果知道服务器返回的XML， xhr.responseType应该为document
+                    context.content = xhr.response;
+                }
+                context.type = 'success';
+                successHandler({ ...context });
+            } else {
+                //失败回调
+                context.content = xhr.response;
+                context.type = isInformation ? 'infomation' : isRedirection ? 'redirection' : isClientError ? 'client-error' : isServerError ? 'server-error' : 'unknown-error';
+                //
+                if (isInformation) {
+                    config?.onInformation?.({ ...context });
+                } else if (isRedirection) {
+                    config?.onRedirection?.({ ...context });
+                } else {
+                    errorHandler({ ...context });
+                }
+                //
+                config?.onFailure?.({ ...context });
+            }
+            config?.onFinish?.({ ...context });
+        };
+
+        //发送异步请求
+        let openParams: (string | boolean)[] = [method, config.url, config.async];
+        if (methodsWithoutBody.includes(method)) {
+            // 拼接url => xxx.com?a=0&b=1#hello
+            const url = buildUrl({
+                url: config.url,
+                data: requestData,
+                cacheBustKey: config.cacheBustKey,
+                appendCacheBust: true,
+            });
+            openParams = [method, url, config.async];
+        }
+
+        //设置xhr其他字段
+        for (let k in config.xhrFields) {
+            config.xhrFields.hasOwnProperty(k) && (xhr[k] = config.xhrFields[k]);
+        }
+        //与服务器建立连接
+        xhr.open(...openParams);
+
+        //有则设置，仅跳过空内容
+        for (let k in config.headers) {
+            config.headers.hasOwnProperty(k) && !isEmpty(config.headers[k]) && xhr.setRequestHeader(k, config.headers[k]);
+        }
+
+        config?.onBeforeSend?.(({ ...context, status: xhr.status, type: 'beforeSend' }));
+        //发送请求，get和head不需要发送数据
+        xhr.send(methodsWithoutBody.includes(method) ? null : (requestData || null));
+        //open和send阶段已经是异步了，无法使用try+catch捕获错误
+    });
+    //绑定xhr和abort
+    (result as any).xhr = xhr;
+    (result as any).abort = () => xhr.abort();
+    return result;
+};
+// Static Helper Methods
+//get、head、trace是不需要发送数据的，data将被转为url参数处理
+['post', 'put', 'delete', 'patch', 'options', 'get', 'head', 'trace'].forEach(method => {
+    (ajax as any)[method] = (url: string, data: any, options: AjaxOptions = { url: '' }) =>
+        ajax({ ...options, method, url, data });
+});
+
+ajax.all = (requests: AjaxOptions[]): Promise<AjaxResponse[]> => Promise.all(requests.map(ajax) as any);
+
+export default ajax;

package/src/buildUrl.js

@@ -0,0 +1,64 @@
+/**
+ * @since Last modified: 2026/01/20 13:56:36
+ * Builds a URL with query parameters, an optional cache-busting key, and preserves the hash.
+ * This function processes the base URL, appends query parameters, and optionally adds a cache-busting parameter.
+ * It also keeps the hash fragment intact if it exists in the original URL.
+ *
+ * @param {string} url - The original URL string that may or may not contain query parameters and a hash.
+ * @param {string | Record<string, string> | URLSearchParams} [data] - The data to be appended as query parameters.
+ * This can be a query string, an object, or a `URLSearchParams` object.
+ * @param {string} [cacheBustKey='_t'] - The cache-busting query parameter key to be appended to the URL. Default is '_t'.
+ * @param {boolean} [appendCacheBust=true] - A flag to indicate whether to append the cache-busting parameter. Default is true.
+ *
+ * @returns {string} The final constructed URL with the original URL, query parameters, and hash (if any).
+ *
+ * @example
+ * buildUrl({
+ *   url: '/api/data',
+ *   data: { key: 'value' },
+ *   cacheBustKey: '_cache',
+ *   appendCacheBust: true
+ * });
+ * // Returns: '/api/data?key=value&_cache=1638311234567'
+ */
+import cleanQueryString from "./cleanQueryString";
+import getDataType from "./getDataType";
+import isEmpty from "./isEmpty";
+const buildUrl = ({ url, data, cacheBustKey = '_t', appendCacheBust = true }) => {
+    // 1. Extract and remove the hash (e.g., /page#section -> hash="#section")
+    const hashIndex = url.indexOf('#');
+    let hash = '', pureUrl = url;
+    // If a hash exists, separate it from the base URL
+    if (hashIndex !== -1) {
+        hash = url.slice(hashIndex);
+        pureUrl = url.slice(0, hashIndex);
+    }
+    // 2. Use the URL object to handle the base URL and existing query parameters.
+    // `window.location.origin` ensures the support for relative paths (e.g., '/api/list').
+    const urlObj = new URL(pureUrl, window.location.origin);
+    // 3. Append business data (query parameters) to the URL if data is not empty
+    if (!isEmpty(data)) {
+        let params, dataType = getDataType(data);
+        // If the data is a URLSearchParams object, directly use it
+        if (dataType === 'URLSearchParams') {
+            params = data;
+        }
+        else if (dataType === 'object') {
+            // If the data is an object, convert it to URLSearchParams
+            params = new URLSearchParams(data);
+        }
+        else {
+            // If the data is a string, clean it up (remove leading '?' or '&')
+            params = new URLSearchParams(cleanQueryString(data));
+        }
+        // Append new parameters to the existing URL search parameters
+        params.forEach((value, key) => {
+            urlObj.searchParams.append(key, value);
+        });
+    }
+    // 4. Optionally add the cache-busting parameter if the flag is set
+    appendCacheBust && cacheBustKey && urlObj.searchParams.set(cacheBustKey, Date.now().toString());
+    // 5. Return the final URL: base URL + query parameters + original hash (if any)
+    return urlObj.toString() + hash;
+};
+export default buildUrl;

package/src/buildUrl.ts

@@ -0,0 +1,86 @@
+
+
+/**
+ * @since Last modified: 2026/01/20 13:56:36
+ * Builds a URL with query parameters, an optional cache-busting key, and preserves the hash.
+ * This function processes the base URL, appends query parameters, and optionally adds a cache-busting parameter.
+ * It also keeps the hash fragment intact if it exists in the original URL.
+ * 
+ * @param {string} url - The original URL string that may or may not contain query parameters and a hash.
+ * @param {string | Record<string, string> | URLSearchParams} [data] - The data to be appended as query parameters.
+ * This can be a query string, an object, or a `URLSearchParams` object.
+ * @param {string} [cacheBustKey='_t'] - The cache-busting query parameter key to be appended to the URL. Default is '_t'.
+ * @param {boolean} [appendCacheBust=true] - A flag to indicate whether to append the cache-busting parameter. Default is true.
+ * 
+ * @returns {string} The final constructed URL with the original URL, query parameters, and hash (if any).
+ * 
+ * @example
+ * buildUrl({
+ *   url: '/api/data',
+ *   data: { key: 'value' },
+ *   cacheBustKey: '_cache',
+ *   appendCacheBust: true
+ * });
+ * // Returns: '/api/data?key=value&_cache=1638311234567'
+ */
+
+import cleanQueryString from "./cleanQueryString";
+import getDataType from "./getDataType";
+import isEmpty from "./isEmpty";
+
+const buildUrl = ({
+    url,
+    data,
+    cacheBustKey = '_t',
+    appendCacheBust = true
+}: {
+    url: string;
+    data?: string | Record<string, string> | URLSearchParams;
+    cacheBustKey?: string;
+    appendCacheBust?: boolean;
+}): string => {
+    // 1. Extract and remove the hash (e.g., /page#section -> hash="#section")
+    const hashIndex = url.indexOf('#');
+    let hash = '',
+        pureUrl = url;
+
+    // If a hash exists, separate it from the base URL
+    if (hashIndex !== -1) {
+        hash = url.slice(hashIndex);
+        pureUrl = url.slice(0, hashIndex);
+    }
+
+    // 2. Use the URL object to handle the base URL and existing query parameters.
+    // `window.location.origin` ensures the support for relative paths (e.g., '/api/list').
+    const urlObj = new URL(pureUrl, window.location.origin);
+
+    // 3. Append business data (query parameters) to the URL if data is not empty
+    if (!isEmpty(data)) {
+        let params: URLSearchParams,
+            dataType = getDataType(data);
+
+        // If the data is a URLSearchParams object, directly use it
+        if (dataType === 'URLSearchParams') {
+            params = data as URLSearchParams;
+        } else if (dataType === 'object') {
+            // If the data is an object, convert it to URLSearchParams
+            params = new URLSearchParams(data);
+        } else {
+            // If the data is a string, clean it up (remove leading '?' or '&')
+            params = new URLSearchParams(cleanQueryString(data as string));
+        }
+
+        // Append new parameters to the existing URL search parameters
+        params.forEach((value, key) => {
+            urlObj.searchParams.append(key, value);
+        });
+    }
+
+    // 4. Optionally add the cache-busting parameter if the flag is set
+    appendCacheBust && cacheBustKey && urlObj.searchParams.set(cacheBustKey, Date.now().toString());
+
+    // 5. Return the final URL: base URL + query parameters + original hash (if any)
+    return urlObj.toString() + hash;
+};
+
+export default buildUrl;

package/src/capitalize.js

@@ -0,0 +1,19 @@
+/**
+ * @since Last modified: 2026/01/20 11:52:35
+ * Capitalizes the first letter of the given string.
+ *
+ * This function takes a string as input and returns a new string with the first letter
+ * capitalized, while leaving the rest of the string unchanged. If the input string is
+ * empty or undefined, it returns the input string as is.
+ *
+ * @param str - The string whose first letter will be capitalized.
+ * @returns A new string with the first letter capitalized, or the input string if it's empty.
+ */
+const capitalize = (str) => {
+    // Check if the input string is empty or undefined
+    if (!str)
+        return str;
+    // Capitalize the first letter and return the new string
+    return str.charAt(0).toUpperCase() + str.slice(1);
+};
+export default capitalize;

package/src/capitalize.ts

@@ -0,0 +1,20 @@
+/**
+ * @since Last modified: 2026/01/20 11:52:35
+ * Capitalizes the first letter of the given string.
+ * 
+ * This function takes a string as input and returns a new string with the first letter
+ * capitalized, while leaving the rest of the string unchanged. If the input string is 
+ * empty or undefined, it returns the input string as is.
+ * 
+ * @param str - The string whose first letter will be capitalized.
+ * @returns A new string with the first letter capitalized, or the input string if it's empty.
+ */
+const capitalize = (str: string): string => {
+    // Check if the input string is empty or undefined
+    if (!str) return str; 
+    
+    // Capitalize the first letter and return the new string
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export default capitalize;

package/src/cleanQueryString.js

@@ -0,0 +1,19 @@
+/**
+ * @since Last modified: 2026/01/20 13:55:13
+ * Cleans a query string by removing the leading '?' or '&' character if it exists.
+ * This ensures that the string is in a valid format for use in URLSearchParams.
+ *
+ * @param {string} data - The query string to clean.
+ * @returns {string} The cleaned query string without leading '?' or '&'.
+ *
+ * @example
+ * cleanQueryString('?key=value&name=John'); // Returns 'key=value&name=John'
+ * cleanQueryString('&key=value&name=John'); // Returns 'key=value&name=John'
+ * cleanQueryString('key=value&name=John'); // Returns 'key=value&name=John'
+ */
+const cleanQueryString = (data) => {
+    return typeof data === 'string' && (data.startsWith('?') || data.startsWith('&'))
+        ? data.slice(1) // Remove the leading '?' or '&'
+        : data; // Return the string as-is if no leading character is present
+};
+export default cleanQueryString;