@catbee/utils 0.0.6 → 0.0.8-next.0

package/build/src/utils/response.utils.js

@@ -1,260 +0,0 @@
-"use strict";
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies
- *
- * 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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RedirectResponse = exports.NoContentResponse = exports.PaginatedResponse = exports.ErrorResponse = exports.SuccessResponse = void 0;
-exports.createSuccessResponse = createSuccessResponse;
-exports.createErrorResponse = createErrorResponse;
-exports.createFinalErrorResponse = createFinalErrorResponse;
-exports.createPaginatedResponse = createPaginatedResponse;
-exports.sendResponse = sendResponse;
-const context_store_utils_1 = require("./context-store.utils");
-const env_utils_1 = require("./env.utils");
-const id_utils_1 = require("./id.utils");
-/**
- * Standard HTTP response wrapper for successful responses.
- * Implements the `ApiResponse<T>` interface and sets default values.
- *
- * @typeParam T - The shape of the data returned in the response.
- */
-class SuccessResponse {
-    /**
-     * Constructs a new success response.
-     *
-     * @param {string} message - Optional message to override the default.
-     * @param {T} [data] - Optional data payload.
-     */
-    constructor(message, data) {
-        var _a;
-        /** Message describing the result of the operation. */
-        this.message = 'Success';
-        /** Whether the response is an error. Always false in success responses. */
-        this.error = false;
-        /** The payload returned from the API. */
-        this.data = null;
-        /** Timestamp when the response was generated, in ISO format. */
-        this.timestamp = new Date().toISOString();
-        /** Unique identifier for this response, useful for request tracing. */
-        this.requestId = (_a = (0, context_store_utils_1.getRequestId)()) !== null && _a !== void 0 ? _a : (0, id_utils_1.uuid)();
-        if (message)
-            this.message = message;
-        this.data = data !== null && data !== void 0 ? data : null;
-    }
-}
-exports.SuccessResponse = SuccessResponse;
-/**
- * Wrapper for error responses that extends the native `Error` object.
- * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).
- */
-class ErrorResponse extends Error {
-    /**
-     * Constructs a new error response.
-     *
-     * @param {string} message - The error message to display or log.
-     * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
-     */
-    constructor(message, status = 500) {
-        var _a;
-        super(message);
-        /** Indicates that this is an error. Always true. */
-        this.error = true;
-        /** Timestamp when the error occurred, in ISO format. */
-        this.timestamp = new Date().toISOString();
-        /** Unique identifier for this error instance. */
-        this.requestId = (_a = (0, context_store_utils_1.getRequestId)()) !== null && _a !== void 0 ? _a : (0, id_utils_1.uuid)();
-        this.status = status;
-        this.name = this.constructor.name;
-        Error.captureStackTrace(this, this.constructor);
-    }
-}
-exports.ErrorResponse = ErrorResponse;
-/**
- * Response with paginated data extending the standard success response.
- * Useful for APIs that return large collections of data.
- *
- * @typeParam T - The shape of each item in the paginated collection.
- */
-class PaginatedResponse extends SuccessResponse {
-    /**
-     * Constructs a new paginated response.
-     *
-     * @param {T[]} items - The current page of items.
-     * @param {Object} pagination - Pagination information.
-     * @param {number} pagination.total - Total number of items across all pages.
-     * @param {number} pagination.page - Current page number (1-based).
-     * @param {number} pagination.pageSize - Number of items per page.
-     * @param {string} [message="Success"] - Optional custom message.
-     */
-    constructor(items, pagination, message = 'Success') {
-        super(message, items);
-        this.total = pagination.total;
-        this.page = pagination.page;
-        this.pageSize = pagination.pageSize;
-        this.totalPages = Math.ceil(this.total / this.pageSize);
-        this.hasNext = this.page < this.totalPages;
-        this.hasPrevious = this.page > 1;
-    }
-}
-exports.PaginatedResponse = PaginatedResponse;
-/**
- * Specialized response for operations that don't return data (HTTP 204).
- */
-class NoContentResponse extends SuccessResponse {
-    /**
-     * Constructs a new no-content response.
-     *
-     * @param {string} [message="Operation completed successfully"] - Optional custom message.
-     */
-    constructor(message = 'Operation completed successfully') {
-        super(message, null);
-    }
-}
-exports.NoContentResponse = NoContentResponse;
-/**
- * Specialized response for redirects.
- */
-class RedirectResponse {
-    /**
-     * Constructs a new redirect response.
-     *
-     * @param {string} url - The URL to redirect to.
-     * @param {number} [statusCode=302] - HTTP status code for the redirect.
-     */
-    constructor(url, statusCode = 302) {
-        var _a;
-        /** Whether the response is a redirect */
-        this.isRedirect = true;
-        /** Unique identifier for this response */
-        this.requestId = (_a = (0, context_store_utils_1.getRequestId)()) !== null && _a !== void 0 ? _a : (0, id_utils_1.uuid)();
-        this.redirectUrl = url;
-        this.statusCode = statusCode;
-    }
-}
-exports.RedirectResponse = RedirectResponse;
-/**
- * Creates a standard success response.
- *
- * @typeParam T - The shape of the data returned in the response.
- * @param {T} data - The data to include in the response.
- * @param {string} [message="Success"] - Optional custom message.
- * @returns {SuccessResponse<T>} A properly formatted success response.
- */
-function createSuccessResponse(data, message = 'Success') {
-    return new SuccessResponse(message, data);
-}
-/**
- * Creates a standard error response.
- *
- * @param {string} message - The error message.
- * @param {number} [statusCode=500] - HTTP status code for the error.
- * @returns {ErrorResponse} A properly formatted error response.
- */
-function createErrorResponse(message, statusCode = 500) {
-    return new ErrorResponse(message, statusCode);
-}
-/**
- * Creates a final error response with request information.
- *
- * @param req - The original request object.
- * @param status - The HTTP status code.
- * @param message - The error message.
- * @param error - The original error object (optional).
- * @param options - Additional options for the response (optional).
- * @returns A properly formatted final error response.
- */
-function createFinalErrorResponse(req, status, message, error, options) {
-    const isDev = env_utils_1.Env.isDev();
-    const includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) && isDev;
-    const response = {
-        error: true,
-        message,
-        timestamp: new Date().toISOString(),
-        requestId: (error === null || error === void 0 ? void 0 : error.requestId) || (req === null || req === void 0 ? void 0 : req.id) || (0, id_utils_1.uuid)(),
-        status,
-        path: req.originalUrl || req.url
-    };
-    // Include stack trace in development mode if requested
-    if (includeDetails && (error === null || error === void 0 ? void 0 : error.stack)) {
-        response.stack = error.stack.split('\n').map((line) => line.trim());
-    }
-    return response;
-}
-/**
- * Creates a paginated response from array data.
- *
- * @typeParam T - The shape of each item in the collection.
- * @param {T[]} allItems - The complete array of items to paginate.
- * @param {number} page - The requested page (1-based).
- * @param {number} pageSize - The number of items per page.
- * @param {string} [message="Success"] - Optional custom message.
- * @returns {PaginatedResponse<T>} A properly formatted paginated response.
- */
-function createPaginatedResponse(allItems, page, pageSize, message = 'Success') {
-    // Ensure valid pagination parameters
-    const validPage = Math.max(1, page);
-    const validPageSize = Math.max(1, pageSize);
-    // Calculate slice indices
-    const startIndex = (validPage - 1) * validPageSize;
-    const endIndex = startIndex + validPageSize;
-    // Get current page items
-    const pageItems = allItems.slice(startIndex, endIndex);
-    return new PaginatedResponse(pageItems, {
-        total: allItems.length,
-        page: validPage,
-        pageSize: validPageSize
-    }, message);
-}
-/**
- * Adapter to convert API responses to Express.js response format.
- *
- * @param {any} res - Express response object.
- * @param {SuccessResponse<any> | ErrorResponse | RedirectResponse} apiResponse - API response instance.
- */
-function sendResponse(res, apiResponse) {
-    // Handle redirects
-    if ('redirectUrl' in apiResponse) {
-        res.redirect(apiResponse.statusCode, apiResponse.redirectUrl);
-        return;
-    }
-    // Handle errors
-    if ('error' in apiResponse && apiResponse.error) {
-        const errorResponse = apiResponse;
-        res.status(errorResponse.status).json({
-            error: true,
-            message: errorResponse.message,
-            timestamp: errorResponse.timestamp,
-            requestId: errorResponse.requestId
-        });
-        return;
-    }
-    // Handle success responses
-    const successResponse = apiResponse;
-    // No content (204) shouldn't return a body
-    if (successResponse instanceof NoContentResponse) {
-        res.status(204).end();
-        return;
-    }
-    res.status(200).json(successResponse);
-}
-//# sourceMappingURL=response.utils.js.map

package/build/src/utils/response.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"response.utils.js","sourceRoot":"","sources":["../../../src/utils/response.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Request } from 'express';\nimport { ApiErrorResponse, ApiResponse } from '../types/api-response';\nimport { getRequestId } from './context-store.utils';\nimport { Env } from './env.utils';\nimport { uuid } from './id.utils';\n\n/**\n * Standard HTTP response wrapper for successful responses.\n * Implements the `ApiResponse<T>` interface and sets default values.\n *\n * @typeParam T - The shape of the data returned in the response.\n */\nexport class SuccessResponse<T> implements ApiResponse<T> {\n  /** Message describing the result of the operation. */\n  message: string = 'Success';\n\n  /** Whether the response is an error. Always false in success responses. */\n  error: boolean = false;\n\n  /** The payload returned from the API. */\n  data: T | null = null;\n\n  /** Timestamp when the response was generated, in ISO format. */\n  timestamp: string = new Date().toISOString();\n\n  /** Unique identifier for this response, useful for request tracing. */\n  requestId: string = getRequestId() ?? uuid();\n\n  /**\n   * Constructs a new success response.\n   *\n   * @param {string} message - Optional message to override the default.\n   * @param {T} [data] - Optional data payload.\n   */\n  constructor(message: string, data?: T) {\n    if (message) this.message = message;\n    this.data = data ?? null;\n  }\n}\n\n/**\n * Wrapper for error responses that extends the native `Error` object.\n * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).\n */\nexport class ErrorResponse extends Error implements Omit<ApiResponse<never>, 'data'> {\n  /** HTTP status code associated with the error (e.g., 404, 500). */\n  status: number;\n\n  /** Indicates that this is an error. Always true. */\n  error: boolean = true;\n\n  /** Timestamp when the error occurred, in ISO format. */\n  timestamp: string = new Date().toISOString();\n\n  /** Unique identifier for this error instance. */\n  requestId: string = getRequestId() ?? uuid();\n\n  /**\n   * Constructs a new error response.\n   *\n   * @param {string} message - The error message to display or log.\n   * @param {number} [status=500] - Optional HTTP status code (defaults to 500).\n   */\n  constructor(message: string, status: number = 500) {\n    super(message);\n    this.status = status;\n    this.name = this.constructor.name;\n    Error.captureStackTrace(this, this.constructor);\n  }\n}\n\n/**\n * Response with paginated data extending the standard success response.\n * Useful for APIs that return large collections of data.\n *\n * @typeParam T - The shape of each item in the paginated collection.\n */\nexport class PaginatedResponse<T> extends SuccessResponse<T[]> {\n  /** Total number of items across all pages */\n  total: number;\n\n  /** Current page number (1-based) */\n  page: number;\n\n  /** Number of items per page */\n  pageSize: number;\n\n  /** Total number of pages */\n  totalPages: number;\n\n  /** Whether there's a next page available */\n  hasNext: boolean;\n\n  /** Whether there's a previous page available */\n  hasPrevious: boolean;\n\n  /**\n   * Constructs a new paginated response.\n   *\n   * @param {T[]} items - The current page of items.\n   * @param {Object} pagination - Pagination information.\n   * @param {number} pagination.total - Total number of items across all pages.\n   * @param {number} pagination.page - Current page number (1-based).\n   * @param {number} pagination.pageSize - Number of items per page.\n   * @param {string} [message=\"Success\"] - Optional custom message.\n   */\n  constructor(items: T[], pagination: { total: number; page: number; pageSize: number }, message: string = 'Success') {\n    super(message, items);\n\n    this.total = pagination.total;\n    this.page = pagination.page;\n    this.pageSize = pagination.pageSize;\n\n    this.totalPages = Math.ceil(this.total / this.pageSize);\n    this.hasNext = this.page < this.totalPages;\n    this.hasPrevious = this.page > 1;\n  }\n}\n\n/**\n * Specialized response for operations that don't return data (HTTP 204).\n */\nexport class NoContentResponse extends SuccessResponse<null> {\n  /**\n   * Constructs a new no-content response.\n   *\n   * @param {string} [message=\"Operation completed successfully\"] - Optional custom message.\n   */\n  constructor(message: string = 'Operation completed successfully') {\n    super(message, null);\n  }\n}\n\n/**\n * Specialized response for redirects.\n */\nexport class RedirectResponse {\n  /** The URL to redirect to */\n  redirectUrl: string;\n\n  /** HTTP status code for the redirect (301, 302, 303, 307, 308) */\n  statusCode: number;\n\n  /** Whether the response is a redirect */\n  isRedirect: boolean = true;\n\n  /** Unique identifier for this response */\n  requestId: string = getRequestId() ?? uuid();\n\n  /**\n   * Constructs a new redirect response.\n   *\n   * @param {string} url - The URL to redirect to.\n   * @param {number} [statusCode=302] - HTTP status code for the redirect.\n   */\n  constructor(url: string, statusCode: number = 302) {\n    this.redirectUrl = url;\n    this.statusCode = statusCode;\n  }\n}\n\n/**\n * Creates a standard success response.\n *\n * @typeParam T - The shape of the data returned in the response.\n * @param {T} data - The data to include in the response.\n * @param {string} [message=\"Success\"] - Optional custom message.\n * @returns {SuccessResponse<T>} A properly formatted success response.\n */\nexport function createSuccessResponse<T>(data: T, message: string = 'Success'): SuccessResponse<T> {\n  return new SuccessResponse<T>(message, data);\n}\n\n/**\n * Creates a standard error response.\n *\n * @param {string} message - The error message.\n * @param {number} [statusCode=500] - HTTP status code for the error.\n * @returns {ErrorResponse} A properly formatted error response.\n */\nexport function createErrorResponse(message: string, statusCode: number = 500): ErrorResponse {\n  return new ErrorResponse(message, statusCode);\n}\n\n/**\n * Creates a final error response with request information.\n *\n * @param req - The original request object.\n * @param status - The HTTP status code.\n * @param message - The error message.\n * @param error - The original error object (optional).\n * @param options - Additional options for the response (optional).\n * @returns A properly formatted final error response.\n */\nexport function createFinalErrorResponse(\n  req: Request,\n  status: number,\n  message: string,\n  error?: any,\n  options?: { includeDetails?: boolean }\n) {\n  const isDev = Env.isDev();\n  const includeDetails = options?.includeDetails && isDev;\n\n  const response: ApiErrorResponse = {\n    error: true,\n    message,\n    timestamp: new Date().toISOString(),\n    requestId: error?.requestId || req?.id || uuid(),\n    status,\n    path: req.originalUrl || req.url\n  };\n\n  // Include stack trace in development mode if requested\n  if (includeDetails && error?.stack) {\n    response.stack = error.stack.split('\\n').map((line: string) => line.trim());\n  }\n\n  return response;\n}\n\n/**\n * Creates a paginated response from array data.\n *\n * @typeParam T - The shape of each item in the collection.\n * @param {T[]} allItems - The complete array of items to paginate.\n * @param {number} page - The requested page (1-based).\n * @param {number} pageSize - The number of items per page.\n * @param {string} [message=\"Success\"] - Optional custom message.\n * @returns {PaginatedResponse<T>} A properly formatted paginated response.\n */\nexport function createPaginatedResponse<T>(\n  allItems: T[],\n  page: number,\n  pageSize: number,\n  message: string = 'Success'\n): PaginatedResponse<T> {\n  // Ensure valid pagination parameters\n  const validPage = Math.max(1, page);\n  const validPageSize = Math.max(1, pageSize);\n\n  // Calculate slice indices\n  const startIndex = (validPage - 1) * validPageSize;\n  const endIndex = startIndex + validPageSize;\n\n  // Get current page items\n  const pageItems = allItems.slice(startIndex, endIndex);\n\n  return new PaginatedResponse<T>(\n    pageItems,\n    {\n      total: allItems.length,\n      page: validPage,\n      pageSize: validPageSize\n    },\n    message\n  );\n}\n\n/**\n * Adapter to convert API responses to Express.js response format.\n *\n * @param {any} res - Express response object.\n * @param {SuccessResponse<any> | ErrorResponse | RedirectResponse} apiResponse - API response instance.\n */\nexport function sendResponse(res: any, apiResponse: SuccessResponse<any> | ErrorResponse | RedirectResponse): void {\n  // Handle redirects\n  if ('redirectUrl' in apiResponse) {\n    res.redirect(apiResponse.statusCode, apiResponse.redirectUrl);\n    return;\n  }\n\n  // Handle errors\n  if ('error' in apiResponse && apiResponse.error) {\n    const errorResponse = apiResponse as ErrorResponse;\n    res.status(errorResponse.status).json({\n      error: true,\n      message: errorResponse.message,\n      timestamp: errorResponse.timestamp,\n      requestId: errorResponse.requestId\n    });\n    return;\n  }\n\n  // Handle success responses\n  const successResponse = apiResponse as SuccessResponse<any>;\n\n  // No content (204) shouldn't return a body\n  if (successResponse instanceof NoContentResponse) {\n    res.status(204).end();\n    return;\n  }\n\n  res.status(200).json(successResponse);\n}\n"]}

package/build/src/utils/string.utils.d.ts

@@ -1,93 +0,0 @@
-/**
- * Capitalizes the first character of a string.
- *
- * @param {string} str - The input string.
- * @returns {string} The string with the first character in uppercase.
- */
-export declare function capitalize(str: string): string;
-/**
- * Converts a string to kebab-case (e.g., "FooBar test" → "foo-bar-test").
- *
- * @param {string} str - The input string.
- * @returns {string} The kebab-cased string.
- */
-export declare function toKebabCase(str: string): string;
-/**
- * Converts a kebab-case or snake_case string to camelCase.
- *
- * @param {string} str - The input string.
- * @returns {string} The camelCased string.
- */
-export declare function toCamelCase(str: string): string;
-/**
- * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
- *
- * @param {string} str - The input string.
- * @returns {string} The slugified string.
- */
-export declare function slugify(str: string): string;
-/**
- * Truncates a string to a specific length, appending '...' if truncated.
- *
- * @param {string} str - The input string.
- * @param {number} len - The maximum length.
- * @returns {string} The truncated string.
- */
-export declare function truncate(str: string, len: number): string;
-/**
- * Converts a string to PascalCase (e.g., "foo-bar" → "FooBar").
- *
- * @param {string} str - The input string.
- * @returns {string} The PascalCased string.
- */
-export declare function toPascalCase(str: string): string;
-/**
- * Converts a string to snake_case (e.g., "FooBar test" → "foo_bar_test").
- *
- * @param {string} str - The input string.
- * @returns {string} The snake_cased string.
- */
-export declare function toSnakeCase(str: string): string;
-/**
- * Masks a string by replacing characters with a mask character.
- * Useful for hiding sensitive information like credit cards or passwords.
- *
- * @param {string} str - The string to mask.
- * @param {number} [visibleStart=0] - Number of characters to show at start.
- * @param {number} [visibleEnd=0] - Number of characters to show at end.
- * @param {string} [maskChar="*"] - Character to use for masking.
- * @returns {string} The masked string.
- */
-export declare function mask(str: string, visibleStart?: number, visibleEnd?: number, maskChar?: string): string;
-/**
- * Removes all HTML tags from a string.
- *
- * @param {string} str - The HTML string to process.
- * @returns {string} The string with HTML tags removed.
- */
-export declare function stripHtml(str: string): string;
-/**
- * Performs case-insensitive string comparison.
- *
- * @param {string} a - First string.
- * @param {string} b - Second string.
- * @returns {boolean} True if the strings are equal ignoring case.
- */
-export declare function equalsIgnoreCase(a: string, b: string): boolean;
-/**
- * Reverses a string.
- *
- * @param {string} str - The string to reverse.
- * @returns {string} The reversed string.
- */
-export declare function reverse(str: string): string;
-/**
- * Counts occurrences of a substring within a string.
- *
- * @param {string} str - The source string.
- * @param {string} substring - The substring to count.
- * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.
- * @returns {number} Number of occurrences.
- */
-export declare function countOccurrences(str: string, substring: string, caseSensitive?: boolean): number;
-//# sourceMappingURL=string.utils.d.ts.map

package/build/src/utils/string.utils.js

@@ -1,179 +0,0 @@
-"use strict";
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies
- *
- * 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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.capitalize = capitalize;
-exports.toKebabCase = toKebabCase;
-exports.toCamelCase = toCamelCase;
-exports.slugify = slugify;
-exports.truncate = truncate;
-exports.toPascalCase = toPascalCase;
-exports.toSnakeCase = toSnakeCase;
-exports.mask = mask;
-exports.stripHtml = stripHtml;
-exports.equalsIgnoreCase = equalsIgnoreCase;
-exports.reverse = reverse;
-exports.countOccurrences = countOccurrences;
-/**
- * Capitalizes the first character of a string.
- *
- * @param {string} str - The input string.
- * @returns {string} The string with the first character in uppercase.
- */
-function capitalize(str) {
-    return str.length === 0 ? '' : str.charAt(0).toUpperCase() + str.slice(1);
-}
-/**
- * Converts a string to kebab-case (e.g., "FooBar test" → "foo-bar-test").
- *
- * @param {string} str - The input string.
- * @returns {string} The kebab-cased string.
- */
-function toKebabCase(str) {
-    return str
-        .replace(/([a-z])([A-Z])/g, '$1-$2') // camelCase -> camel-Case
-        .replace(/\s+/g, '-') // spaces to dash
-        .replace(/_+/g, '-') // underscores to dash
-        .toLowerCase();
-}
-/**
- * Converts a kebab-case or snake_case string to camelCase.
- *
- * @param {string} str - The input string.
- * @returns {string} The camelCased string.
- */
-function toCamelCase(str) {
-    return str.replace(/[-_](.)/g, (_, c) => c.toUpperCase());
-}
-/**
- * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
- *
- * @param {string} str - The input string.
- * @returns {string} The slugified string.
- */
-function slugify(str) {
-    return str
-        .toLowerCase()
-        .replace(/[^\w\s-]/g, '') // remove non-word
-        .replace(/\s+/g, '-') // spaces to dash
-        .replace(/-+/g, '-') // multiple dashes to one
-        .replace(/^-+|-+$/g, ''); // trim leading/trailing dashes
-}
-/**
- * Truncates a string to a specific length, appending '...' if truncated.
- *
- * @param {string} str - The input string.
- * @param {number} len - The maximum length.
- * @returns {string} The truncated string.
- */
-function truncate(str, len) {
-    return str.length > len ? str.slice(0, len) + '...' : str;
-}
-/**
- * Converts a string to PascalCase (e.g., "foo-bar" → "FooBar").
- *
- * @param {string} str - The input string.
- * @returns {string} The PascalCased string.
- */
-function toPascalCase(str) {
-    return capitalize(toCamelCase(str));
-}
-/**
- * Converts a string to snake_case (e.g., "FooBar test" → "foo_bar_test").
- *
- * @param {string} str - The input string.
- * @returns {string} The snake_cased string.
- */
-function toSnakeCase(str) {
-    return str
-        .trim()
-        .replace(/([a-z])([A-Z])/g, '$1_$2') // camelCase -> camel_Case
-        .replace(/\s+/g, '_') // spaces to underscore
-        .replace(/-+/g, '_') // dashes to underscore
-        .toLowerCase();
-}
-/**
- * Masks a string by replacing characters with a mask character.
- * Useful for hiding sensitive information like credit cards or passwords.
- *
- * @param {string} str - The string to mask.
- * @param {number} [visibleStart=0] - Number of characters to show at start.
- * @param {number} [visibleEnd=0] - Number of characters to show at end.
- * @param {string} [maskChar="*"] - Character to use for masking.
- * @returns {string} The masked string.
- */
-function mask(str, visibleStart = 0, visibleEnd = 0, maskChar = '*') {
-    if (!str || str.length === 0)
-        return '';
-    if (visibleStart >= str.length)
-        return str;
-    const start = str.slice(0, visibleStart);
-    const end = visibleEnd > 0 ? str.slice(-visibleEnd) : '';
-    const masked = maskChar.repeat(Math.max(0, str.length - visibleStart - visibleEnd));
-    return start + masked + end;
-}
-/**
- * Removes all HTML tags from a string.
- *
- * @param {string} str - The HTML string to process.
- * @returns {string} The string with HTML tags removed.
- */
-function stripHtml(str) {
-    return str.replace(/<[^>]*>/g, '');
-}
-/**
- * Performs case-insensitive string comparison.
- *
- * @param {string} a - First string.
- * @param {string} b - Second string.
- * @returns {boolean} True if the strings are equal ignoring case.
- */
-function equalsIgnoreCase(a, b) {
-    return a.toLowerCase() === b.toLowerCase();
-}
-/**
- * Reverses a string.
- *
- * @param {string} str - The string to reverse.
- * @returns {string} The reversed string.
- */
-function reverse(str) {
-    return str.split('').reverse().join('');
-}
-/**
- * Counts occurrences of a substring within a string.
- *
- * @param {string} str - The source string.
- * @param {string} substring - The substring to count.
- * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.
- * @returns {number} Number of occurrences.
- */
-function countOccurrences(str, substring, caseSensitive = true) {
-    if (!caseSensitive) {
-        str = str.toLowerCase();
-        substring = substring.toLowerCase();
-    }
-    return str.split(substring).length - 1;
-}
-//# sourceMappingURL=string.utils.js.map

package/build/src/utils/string.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"string.utils.js","sourceRoot":"","sources":["../../../src/utils/string.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Capitalizes the first character of a string.\n *\n * @param {string} str - The input string.\n * @returns {string} The string with the first character in uppercase.\n */\nexport function capitalize(str: string): string {\n  return str.length === 0 ? '' : str.charAt(0).toUpperCase() + str.slice(1);\n}\n\n/**\n * Converts a string to kebab-case (e.g., \"FooBar test\" → \"foo-bar-test\").\n *\n * @param {string} str - The input string.\n * @returns {string} The kebab-cased string.\n */\nexport function toKebabCase(str: string): string {\n  return str\n    .replace(/([a-z])([A-Z])/g, '$1-$2') // camelCase -> camel-Case\n    .replace(/\\s+/g, '-') // spaces to dash\n    .replace(/_+/g, '-') // underscores to dash\n    .toLowerCase();\n}\n\n/**\n * Converts a kebab-case or snake_case string to camelCase.\n *\n * @param {string} str - The input string.\n * @returns {string} The camelCased string.\n */\nexport function toCamelCase(str: string): string {\n  return str.replace(/[-_](.)/g, (_, c: string) => c.toUpperCase());\n}\n\n/**\n * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).\n *\n * @param {string} str - The input string.\n * @returns {string} The slugified string.\n */\nexport function slugify(str: string): string {\n  return str\n    .toLowerCase()\n    .replace(/[^\\w\\s-]/g, '') // remove non-word\n    .replace(/\\s+/g, '-') // spaces to dash\n    .replace(/-+/g, '-') // multiple dashes to one\n    .replace(/^-+|-+$/g, ''); // trim leading/trailing dashes\n}\n\n/**\n * Truncates a string to a specific length, appending '...' if truncated.\n *\n * @param {string} str - The input string.\n * @param {number} len - The maximum length.\n * @returns {string} The truncated string.\n */\nexport function truncate(str: string, len: number): string {\n  return str.length > len ? str.slice(0, len) + '...' : str;\n}\n\n/**\n * Converts a string to PascalCase (e.g., \"foo-bar\" → \"FooBar\").\n *\n * @param {string} str - The input string.\n * @returns {string} The PascalCased string.\n */\nexport function toPascalCase(str: string): string {\n  return capitalize(toCamelCase(str));\n}\n\n/**\n * Converts a string to snake_case (e.g., \"FooBar test\" → \"foo_bar_test\").\n *\n * @param {string} str - The input string.\n * @returns {string} The snake_cased string.\n */\nexport function toSnakeCase(str: string): string {\n  return str\n    .trim()\n    .replace(/([a-z])([A-Z])/g, '$1_$2') // camelCase -> camel_Case\n    .replace(/\\s+/g, '_') // spaces to underscore\n    .replace(/-+/g, '_') // dashes to underscore\n    .toLowerCase();\n}\n\n/**\n * Masks a string by replacing characters with a mask character.\n * Useful for hiding sensitive information like credit cards or passwords.\n *\n * @param {string} str - The string to mask.\n * @param {number} [visibleStart=0] - Number of characters to show at start.\n * @param {number} [visibleEnd=0] - Number of characters to show at end.\n * @param {string} [maskChar=\"*\"] - Character to use for masking.\n * @returns {string} The masked string.\n */\nexport function mask(str: string, visibleStart: number = 0, visibleEnd: number = 0, maskChar: string = '*'): string {\n  if (!str || str.length === 0) return '';\n  if (visibleStart >= str.length) return str;\n\n  const start = str.slice(0, visibleStart);\n  const end = visibleEnd > 0 ? str.slice(-visibleEnd) : '';\n  const masked = maskChar.repeat(Math.max(0, str.length - visibleStart - visibleEnd));\n\n  return start + masked + end;\n}\n\n/**\n * Removes all HTML tags from a string.\n *\n * @param {string} str - The HTML string to process.\n * @returns {string} The string with HTML tags removed.\n */\nexport function stripHtml(str: string): string {\n  return str.replace(/<[^>]*>/g, '');\n}\n\n/**\n * Performs case-insensitive string comparison.\n *\n * @param {string} a - First string.\n * @param {string} b - Second string.\n * @returns {boolean} True if the strings are equal ignoring case.\n */\nexport function equalsIgnoreCase(a: string, b: string): boolean {\n  return a.toLowerCase() === b.toLowerCase();\n}\n\n/**\n * Reverses a string.\n *\n * @param {string} str - The string to reverse.\n * @returns {string} The reversed string.\n */\nexport function reverse(str: string): string {\n  return str.split('').reverse().join('');\n}\n\n/**\n * Counts occurrences of a substring within a string.\n *\n * @param {string} str - The source string.\n * @param {string} substring - The substring to count.\n * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.\n * @returns {number} Number of occurrences.\n */\nexport function countOccurrences(str: string, substring: string, caseSensitive: boolean = true): number {\n  if (!caseSensitive) {\n    str = str.toLowerCase();\n    substring = substring.toLowerCase();\n  }\n\n  return str.split(substring).length - 1;\n}\n"]}