web-utils-kit 1.0.16 → 1.1.1

package/README.md

@@ -60,10 +60,12 @@ await res.json();
   ```typescript
   import { isStringValid } from 'web-utils-kit';
 
-  isStringValid(''); // true
+  isStringValid('Hello world!'); // true
   isStringValid('', 1, 5); // false
   isStringValid('abcde', 1, 5); // true
   isStringValid('abcdef', 1, 5); // false
+  isStringValid(' '); // false
+  isStringValid(' ', undefined, undefined, false); // true
   ```
   <br/>
 </details>
@@ -496,6 +498,21 @@ await res.json();
   <br/>
 </details>
 
+<details>
+  <summary><code>toMS</code></summary>
+  <br/>
+
+  Converts a time string into milliseconds. The time string should be in the format of `"{value} {unit}"`, where the **value** is a number and the **unit** can be milliseconds, seconds, minutes, hours, days, weeks, months, or years. For example: `"2 days"`, `"5 minutes"`, `"2 hours"`.
+
+  ```typescript
+  import { toMS } from 'web-utils-kit';
+
+  toMS('53 years'); // 1672552800000
+  toMS('53 days'); // 4579200000
+  ```
+  <br/>
+</details>
+
 <details>
   <summary><code>stringifyJSON</code></summary>
   <br/>
@@ -940,6 +957,37 @@ await res.json();
   <br/>
 </details>
 
+<details>
+  <summary><code>ITimeString</code></summary>
+  <br/>
+  
+  A duration string composed of a numeric value followed by a supported time unit, with or without a space.
+
+  ```typescript
+  type IYears = 'years' | 'year';
+  type IMonths = 'months' | 'month';
+  type IWeeks = 'weeks' | 'week';
+  type IDays = 'days' | 'day';
+  type IHours = 'hours' | 'hour';
+  type IMinutes = 'minutes' | 'minute';
+  type ISeconds = 'seconds' | 'second';
+  type IMilliseconds = 'milliseconds' | 'millisecond';
+  
+  export type IUnit =
+    | IYears
+    | IMonths
+    | IWeeks
+    | IDays
+    | IHours
+    | IMinutes
+    | ISeconds
+    | IMilliseconds;
+
+  export type ITimeString = `${number} ${IUnit}`;
+  ```
+  <br/>
+</details>
+
 <br/>
 
 ## Built With

package/dist/index.d.ts

@@ -1,7 +1,5 @@
-import { IUUIDVersion } from './shared/types.js';
+import type { IJSONValue, IUUIDVersion } from './shared/types.js';
 import { isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid } from './validations/index.js';
-import { INumberFormatConfig, IDateTemplate } from './transformers/types.js';
-import { prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON } from './transformers/index.js';
-import { ISortDirection, IFilterByQueryOptions } from './utils/types.js';
-import { generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction } from './utils/index.js';
-export { type IUUIDVersion, isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid, type INumberFormatConfig, type IDateTemplate, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON, type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction, };
+import { type INumberFormatConfig, type IDateTemplate, type ITimeString, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, toMS, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON } from './transformers/index.js';
+import { type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction } from './utils/index.js';
+export { type IJSONValue, type IUUIDVersion, isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid, type INumberFormatConfig, type IDateTemplate, type ITimeString, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, toMS, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON, type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction, };

package/dist/index.js

@@ -1 +1 @@
-import{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid}from"./validations/index.js";import{prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON}from"./transformers/index.js";import{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction}from"./utils/index.js";export{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid,prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON,generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction};
+import{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid}from"./validations/index.js";import{prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON}from"./transformers/index.js";import{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction}from"./utils/index.js";export{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid,prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON,generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction};

package/dist/shared/errors.d.ts

@@ -1,5 +1,5 @@
-type IErrorCode = 'MIXED_OR_UNSUPPORTED_DATA_TYPES' | 'UNSUPPORTED_DATA_TYPE' | 'INVALID_OR_EMPTY_ARRAY' | 'INVALID_OR_EMPTY_OBJECT' | 'UNABLE_TO_SERIALIZE_JSON' | 'UNABLE_TO_DESERIALIZE_JSON' | 'UNABLE_TO_CREATE_DEEP_CLONE' | 'INVALID_BATCH_SIZE';
-declare const ERRORS: {
+type IErrorCode = 'MIXED_OR_UNSUPPORTED_DATA_TYPES' | 'UNSUPPORTED_DATA_TYPE' | 'INVALID_OR_EMPTY_ARRAY' | 'INVALID_OR_EMPTY_OBJECT' | 'UNABLE_TO_SERIALIZE_JSON' | 'UNABLE_TO_DESERIALIZE_JSON' | 'UNABLE_TO_CREATE_DEEP_CLONE' | 'INVALID_BATCH_SIZE' | 'UNABLE_TO_SLUGIFY_STRING' | 'INVALID_TIME_STRING';
+export declare const ERRORS: {
     [key in IErrorCode]: IErrorCode;
 };
-export { ERRORS };
+export {};

package/dist/shared/errors.js

@@ -1 +1 @@
-const ERRORS={MIXED_OR_UNSUPPORTED_DATA_TYPES:"MIXED_OR_UNSUPPORTED_DATA_TYPES",UNSUPPORTED_DATA_TYPE:"UNSUPPORTED_DATA_TYPE",INVALID_OR_EMPTY_ARRAY:"INVALID_OR_EMPTY_ARRAY",INVALID_OR_EMPTY_OBJECT:"INVALID_OR_EMPTY_OBJECT",UNABLE_TO_SERIALIZE_JSON:"UNABLE_TO_SERIALIZE_JSON",UNABLE_TO_DESERIALIZE_JSON:"UNABLE_TO_DESERIALIZE_JSON",UNABLE_TO_CREATE_DEEP_CLONE:"UNABLE_TO_CREATE_DEEP_CLONE",INVALID_BATCH_SIZE:"INVALID_BATCH_SIZE"};export{ERRORS};
+export const ERRORS={MIXED_OR_UNSUPPORTED_DATA_TYPES:"MIXED_OR_UNSUPPORTED_DATA_TYPES",UNSUPPORTED_DATA_TYPE:"UNSUPPORTED_DATA_TYPE",INVALID_OR_EMPTY_ARRAY:"INVALID_OR_EMPTY_ARRAY",INVALID_OR_EMPTY_OBJECT:"INVALID_OR_EMPTY_OBJECT",UNABLE_TO_SERIALIZE_JSON:"UNABLE_TO_SERIALIZE_JSON",UNABLE_TO_DESERIALIZE_JSON:"UNABLE_TO_DESERIALIZE_JSON",UNABLE_TO_CREATE_DEEP_CLONE:"UNABLE_TO_CREATE_DEEP_CLONE",INVALID_BATCH_SIZE:"INVALID_BATCH_SIZE",UNABLE_TO_SLUGIFY_STRING:"UNABLE_TO_SLUGIFY_STRING",INVALID_TIME_STRING:"INVALID_TIME_STRING"};

package/dist/shared/types.d.ts

@@ -1,6 +1,12 @@
+/**
+ * JSON Value
+ * A value that can be represented in JSON format.
+ */
+export type IJSONValue = string | number | boolean | null | IJSONValue[] | {
+    [key: string]: IJSONValue;
+};
 /**
  * UUID Version
  * The UUID versions supported by this library.
  */
-type IUUIDVersion = 4 | 7;
-export type { IUUIDVersion };
+export type IUUIDVersion = 4 | 7;

package/dist/transformers/consts.d.ts

@@ -1,5 +1,12 @@
-import { IDateTemplateConfigs } from './types.js';
-declare const FILE_SIZE_THRESHOLD: number;
-declare const FILE_SIZE_UNITS: string[];
-declare const DATE_TEMPLATE_CONFIGS: IDateTemplateConfigs;
-export { FILE_SIZE_THRESHOLD, FILE_SIZE_UNITS, DATE_TEMPLATE_CONFIGS };
+import { IDateTemplateConfigs, IUnit } from './types.js';
+export declare const FILE_SIZE_THRESHOLD: number;
+export declare const FILE_SIZE_UNITS: string[];
+export declare const DATE_TEMPLATE_CONFIGS: IDateTemplateConfigs;
+export declare const TIME_STRING_UNITS: IUnit[];
+export declare const ONE_SECOND_IN_MILLISECONDS = 1000;
+export declare const ONE_MINUTE_IN_MILLISECONDS: number;
+export declare const ONE_HOUR_IN_MILLISECONDS: number;
+export declare const ONE_DAY_IN_MILLISECONDS: number;
+export declare const ONE_WEEK_IN_MILLISECONDS: number;
+export declare const ONE_YEAR_IN_MILLISECONDS: number;
+export declare const ONE_MONTH_IN_MILLISECONDS: number;

package/dist/transformers/consts.js

@@ -1 +1 @@
-const FILE_SIZE_THRESHOLD=1024,FILE_SIZE_UNITS=["kB","MB","GB","TB","PB","EB","ZB","YB"],DATE_TEMPLATE_CONFIGS={"date-short":{day:"2-digit",month:"2-digit",year:"numeric"},"date-medium":{day:"numeric",month:"long",year:"numeric"},"date-long":{weekday:"long",day:"numeric",month:"long",year:"numeric"},"time-short":{hour:"2-digit",minute:"2-digit"},"time-medium":{hour:"2-digit",minute:"2-digit",second:"2-digit"},"datetime-short":{day:"numeric",month:"2-digit",year:"numeric",hour:"2-digit",minute:"2-digit"},"datetime-medium":{day:"numeric",month:"long",year:"numeric",hour:"2-digit",minute:"2-digit"},"datetime-long":{weekday:"long",day:"numeric",month:"long",year:"numeric",hour:"2-digit",minute:"2-digit",second:"2-digit"}};export{FILE_SIZE_THRESHOLD,FILE_SIZE_UNITS,DATE_TEMPLATE_CONFIGS};
+export const FILE_SIZE_THRESHOLD=1024;export const FILE_SIZE_UNITS=["kB","MB","GB","TB","PB","EB","ZB","YB"];export const DATE_TEMPLATE_CONFIGS={"date-short":{day:"2-digit",month:"2-digit",year:"numeric"},"date-medium":{day:"numeric",month:"long",year:"numeric"},"date-long":{weekday:"long",day:"numeric",month:"long",year:"numeric"},"time-short":{hour:"2-digit",minute:"2-digit"},"time-medium":{hour:"2-digit",minute:"2-digit",second:"2-digit"},"datetime-short":{day:"numeric",month:"2-digit",year:"numeric",hour:"2-digit",minute:"2-digit"},"datetime-medium":{day:"numeric",month:"long",year:"numeric",hour:"2-digit",minute:"2-digit"},"datetime-long":{weekday:"long",day:"numeric",month:"long",year:"numeric",hour:"2-digit",minute:"2-digit",second:"2-digit"}};export const TIME_STRING_UNITS=["seconds","second","minutes","minute","hours","hour","days","day","weeks","week","months","month","years","year"];export const ONE_SECOND_IN_MILLISECONDS=1e3;export const ONE_MINUTE_IN_MILLISECONDS=6e4;export const ONE_HOUR_IN_MILLISECONDS=36e5;export const ONE_DAY_IN_MILLISECONDS=864e5;export const ONE_WEEK_IN_MILLISECONDS=6048e5;export const ONE_YEAR_IN_MILLISECONDS=315576e5;export const ONE_MONTH_IN_MILLISECONDS=26298e5;

package/dist/transformers/index.d.ts

@@ -1,9 +1,10 @@
-import { IDateTemplate, IJSONValue, INumberFormatConfig } from './types.js';
+import { IJSONValue } from '../shared/types.js';
+import { IDateTemplate, INumberFormatConfig, ITimeString } from './types.js';
 /**
  * Formats a numeric value based on the user's default language.
- * @param value
- * @param configuration?
- * @returns string
+ * @param value The number to be formatted.
+ * @param configuration? An optional configuration object.
+ * @returns A string representing the formatted number.
  */
 declare const prettifyNumber: (value: number, configuration?: Partial<INumberFormatConfig>) => string;
 /**
@@ -16,58 +17,66 @@ declare const prettifyNumber: (value: number, configuration?: Partial<INumberFor
  * - datetime-short: 12/5/2024, 12:05 PM
  * - datetime-medium: December 5, 2024 at 12:05 PM
  * - datetime-long: Thursday, December 5, 2024 at 12:05:20 PM
- * @param value
- * @param template
- * @returns string
+ * @param value The date value to be formatted. It can be a Date object, a timestamp, or a date string.
+ * @param template The template to use for formatting the date.
+ * @returns A string representing the formatted date.
  */
 declare const prettifyDate: (value: Date | number | string, template: IDateTemplate) => string;
 /**
  * Formats a bytes value into a human readable format.
- * @param value
- * @param decimalPlaces
- * @return string
+ * @param value The bytes value to be formatted.
+ * @param decimalPlaces The number of decimal places to include. Defaults to 2.
+ * @returns A string representing the formatted file size.
  */
 declare const prettifyFileSize: (value: number, decimalPlaces?: number) => string;
 /**
  * Formats the number that will be inserted in a badge so it doesn't take too much space. If the
  * current count is 0, it returns undefined as the badge shouldn't be displayed.
- * @param count
- * @param maxValue?
- * @returns string | undefined
+ * @param count The current count to be displayed in the badge.
+ * @param maxValue The maximum value to display before showing a "+" sign. Defaults to 9.
+ * @returns A string representing the formatted badge count or undefined if the count is 0.
  */
 declare const prettifyBadgeCount: (value: number, maxValue?: number) => string | undefined;
 /**
  * Capitalizes the first letter of a string and returns the new value.
- * @param val
- * @returns string
+ * @param val The string value to capitalize.
+ * @returns A string with the first letter capitalized.
  */
 declare const capitalizeFirst: (value: string) => string;
 /**
  * Converts a string value into Title Case.
- * @param value
- * @returns string
+ * @param value The string value to convert.
+ * @returns A string converted to Title Case.
  */
 declare const toTitleCase: (value: string) => string;
 /**
- * Converts a string value into a slug.
- * @param value
- * @returns string
+ * Converts a string value into a slug, meeting the following requirements:
+ * - lowercase
+ * - removes accents/diacritics
+ * - replaces spaces and separators with "-"
+ * - removes invalid URL characters
+ * - collapses repeated "-"
+ * - trims leading/trailing "-"
+ * @param value The string value to convert.
+ * @returns A string converted to a slug.
+ * @throws
+ * - UNABLE_TO_SLUGIFY_STRING: if the resulting slug is empty after processing the input string
  */
 declare const toSlug: (value: string) => string;
 /**
  * Truncates a string to a specified length and appends an ellipsis if it exceeds that length.
- * @param text
- * @param maxLength
- * @returns string
+ * @param text The string value to truncate.
+ * @param maxLength The maximum length of the string before truncation.
+ * @returns A string truncated to the specified length with an ellipsis if necessary.
  */
 declare const truncateText: (text: string, maxLength: number) => string;
 /**
  * Masks the middle of a string, keeping a specified number of visible characters at the start and
  * end.
- * @param text
- * @param visibleChars
- * @param mask?
- * @returns string
+ * @param text The string value to mask.
+ * @param visibleChars The number of characters to keep visible at the start and end of the string.
+ * @param mask? An optional string to use as the mask. Defaults to '...'.
+ * @returns A string with the middle masked, keeping the specified number of visible characters at the start.
  */
 declare const maskMiddle: (text: string, visibleChars: number, mask?: string) => string;
 /**
@@ -78,13 +87,26 @@ declare const maskMiddle: (text: string, visibleChars: number, mask?: string) =>
  * @param input The input string containing placeholders in the format of {{key}}.
  * @param substitutions? An object containing key-value pairs for substitutions. The keys should
  * match the placeholders in the input string, without the curly braces.
- * @returns string
+ * @returns A string with the placeholders replaced by their corresponding values from the substitutions object.
  */
 declare const applySubstitutions: (input: string, substitutions?: Record<string, unknown>) => string;
+/**
+ * Converts a time string into milliseconds. The time string should be in the format of "{value} {unit}",
+ * where the value is a number and the unit can be milliseconds, seconds, minutes, hours, days, weeks,
+ * months, or years. For example: "2 days", "5 minutes", "2 hours".
+ * @param str The time string to convert into milliseconds.
+ * @returns The equivalent time in milliseconds.
+ * @throws
+ * - INVALID_TIME_STRING: if the provided time string is not a valid string.
+ * - INVALID_TIME_STRING: if the chunks do not match the expected format.
+ * - INVALID_TIME_STRING: if the value is not a valid positive integer.
+ * - INVALID_TIME_STRING: if the unit is not one of the accepted values.
+ */
+declare const toMS: (str: ITimeString) => number;
 /**
  * Serializes a JSON object with the JSON.stringify method.
- * @param value
- * @returns string
+ * @param value The value to be serialized. It should be an object or an array.
+ * @returns A string representing the serialized JSON object.
  * @throws
  * - UNSUPPORTED_DATA_TYPE: if the provided value is not an object or an array
  * - UNABLE_TO_SERIALIZE_JSON: if the result of JSON.stringify is not a valid string
@@ -94,8 +116,8 @@ declare const stringifyJSON: <T>(value: T) => string;
 /**
  * Stringifies a JSON object in a deterministic way, ensuring that the keys are sorted and the
  * output is consistent.
- * @param value
- * @returns string
+ * @param value The value to be serialized. It should be an object or an array.
+ * @returns A string representing the serialized JSON object with sorted keys.
  * @throws
  * - UNSUPPORTED_DATA_TYPE: if the provided value is not an object or an array
  * - UNABLE_TO_SERIALIZE_JSON: if the result of JSON.stringify is not a valid string
@@ -104,8 +126,8 @@ declare const stringifyJSON: <T>(value: T) => string;
 declare const stringifyJSONDeterministically: <T>(value: T) => string;
 /**
  * Deserializes a JSON string with the JSON.parse method.
- * @param value
- * @returns T
+ * @param value The JSON string to be deserialized.
+ * @returns The deserialized object or array.
  * @throws
  * - UNSUPPORTED_DATA_TYPE: if the provided value is not a non-empty string
  * - UNABLE_TO_DESERIALIZE_JSON: if the result of JSON.parse is not a valid object or array
@@ -114,16 +136,16 @@ declare const stringifyJSONDeterministically: <T>(value: T) => string;
 declare const parseJSON: <T>(value: string) => T;
 /**
  * Creates a deep clone of an object by using the JSON.stringify and JSON.parse methods.
- * @param value
- * @returns T
+ * @param value The value to be cloned. It should be an object or an array.
+ * @returns A deep clone of the provided value.
  * @throws
  * - UNABLE_TO_CREATE_DEEP_CLONE: if the value cannot be serialized and deserialized
  */
 declare const createDeepClone: <T>(value: T) => T;
 /**
  * Removes null, undefined, empty objects, and empty arrays from the given data recursively.
- * @param value
- * @returns T | null
+ * @param value The value to be pruned. It should be an object, array, or primitive value.
+ * @returns The pruned value, or null if the value is empty or invalid.
  */
 declare const pruneJSON: <T extends IJSONValue>(value: T) => T | null;
-export { prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON, };
+export { type INumberFormatConfig, type IDateTemplate, type ITimeString, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, toMS, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON, };

package/dist/transformers/index.js

@@ -1 +1 @@
-import{decodeError,encodeError,extractMessage}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isObjectValid}from"../validations/index.js";import{DATE_TEMPLATE_CONFIGS,FILE_SIZE_THRESHOLD,FILE_SIZE_UNITS}from"./consts.js";import{canJSONBeSerialized,validateJSONSerializationResult,canJSONBeDeserialized,validateJSONDeserializationResult}from"./validations.js";import{buildNumberFormatConfig,getDateInstance,sortJSONObjectKeys}from"./utils.js";const prettifyNumber=(e,t)=>{const r=buildNumberFormatConfig(t),i=e.toLocaleString(void 0,{minimumFractionDigits:r.minimumFractionDigits,maximumFractionDigits:r.maximumFractionDigits});return`${r.prefix}${i}${r.suffix}`},prettifyDate=(e,t)=>getDateInstance(e).toLocaleString(void 0,DATE_TEMPLATE_CONFIGS[t]),prettifyFileSize=(e,t=2)=>{if("number"==typeof e&&e>0){let r=e;if(Math.abs(e)<FILE_SIZE_THRESHOLD)return`${e} B`;let i=-1;const a=10**t;do{r/=FILE_SIZE_THRESHOLD,i+=1}while(Math.round(Math.abs(r)*a)/a>=FILE_SIZE_THRESHOLD&&i<FILE_SIZE_UNITS.length-1);return`${r.toFixed(t)} ${FILE_SIZE_UNITS[i]}`}return"0 B"},prettifyBadgeCount=(e,t=9)=>{if(0!==e)return e>=t?`${t}+`:String(e)},capitalizeFirst=e=>e.length>0?`${e[0].toUpperCase()}${e.slice(1)}`:"",toTitleCase=e=>e.replace(/\w\S*/g,(e=>e.charAt(0).toUpperCase()+e.substring(1).toLowerCase())),toSlug=e=>e.length>0?e.toLowerCase().replace(/[^\w ]+/g,"").replace(/ +/g,"-"):"",truncateText=(e,t)=>e.length<=t?e:`${e.slice(0,t-3)}...`,maskMiddle=(e,t,r="...")=>e.length<=2*t?e:`${e.slice(0,t)}${r}${e.slice(-t)}`,applySubstitutions=(e,t={})=>e.replace(/{{(.*?)}}/g,((e,r)=>r in t?String(t[r]):e)),stringifyJSON=e=>{try{canJSONBeSerialized(e);const t=JSON.stringify(e);return validateJSONSerializationResult(e,t),t}catch(t){if(decodeError(t).code!==ERRORS.UNABLE_TO_SERIALIZE_JSON)throw new Error(encodeError(`Failed to stringify the JSON value '${e}': ${extractMessage(t)}`,ERRORS.UNABLE_TO_SERIALIZE_JSON));throw t}},stringifyJSONDeterministically=e=>{canJSONBeSerialized(e);try{return stringifyJSON(sortJSONObjectKeys(e))}catch(t){if(decodeError(t).code!==ERRORS.UNABLE_TO_SERIALIZE_JSON)throw new Error(encodeError(`Failed to stringify the JSON value deterministically '${e}': ${extractMessage(t)}`,ERRORS.UNABLE_TO_SERIALIZE_JSON));throw t}},parseJSON=e=>{canJSONBeDeserialized(e);try{const t=JSON.parse(e);return validateJSONDeserializationResult(e,t),t}catch(t){if(decodeError(t).code!==ERRORS.UNABLE_TO_DESERIALIZE_JSON)throw new Error(encodeError(`Failed to parse the JSON value '${e}': ${extractMessage(t)}`,ERRORS.UNABLE_TO_DESERIALIZE_JSON));throw t}},createDeepClone=e=>{try{return parseJSON(stringifyJSON(e))}catch(t){throw new Error(encodeError(`Failed to create a deep clone of the value '${e}': ${extractMessage(t)}`,ERRORS.UNABLE_TO_CREATE_DEEP_CLONE))}},pruneJSON=e=>{if(null==e)return null;if(Array.isArray(e)){const t=e.map((e=>pruneJSON(e))).filter((e=>null!=e&&(Array.isArray(e)?e.length>0:!isObjectValid(e,!0)||Object.keys(e).length>0)));return t.length>0?t:null}if(isObjectValid(e,!0)){const t={};return Object.entries(e).forEach((([e,r])=>{const i=pruneJSON(r);null!=i&&(Array.isArray(i)&&0===i.length||isObjectValid(i,!0)&&!isObjectValid(i)||(t[e]=i))})),Object.keys(t).length>0?t:null}return e};export{prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON};
+import{decodeError,encodeError,extractMessage}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isObjectValid}from"../validations/index.js";import{FILE_SIZE_THRESHOLD,FILE_SIZE_UNITS,DATE_TEMPLATE_CONFIGS,ONE_DAY_IN_MILLISECONDS,ONE_HOUR_IN_MILLISECONDS,ONE_MINUTE_IN_MILLISECONDS,ONE_MONTH_IN_MILLISECONDS,ONE_SECOND_IN_MILLISECONDS,ONE_WEEK_IN_MILLISECONDS,ONE_YEAR_IN_MILLISECONDS}from"./consts.js";import{canJSONBeSerialized,validateJSONSerializationResult,canJSONBeDeserialized,validateJSONDeserializationResult}from"./validations.js";import{buildNumberFormatConfig,getDateInstance,parseTimeString,sortJSONObjectKeys}from"./utils.js";const prettifyNumber=(e,r)=>{const t=buildNumberFormatConfig(r),i=e.toLocaleString(void 0,{minimumFractionDigits:t.minimumFractionDigits,maximumFractionDigits:t.maximumFractionDigits});return`${t.prefix}${i}${t.suffix}`},prettifyDate=(e,r)=>getDateInstance(e).toLocaleString(void 0,DATE_TEMPLATE_CONFIGS[r]),prettifyFileSize=(e,r=2)=>{if("number"==typeof e&&e>0){let t=e;if(Math.abs(e)<FILE_SIZE_THRESHOLD)return`${e} B`;let i=-1;const a=10**r;do{t/=FILE_SIZE_THRESHOLD,i+=1}while(Math.round(Math.abs(t)*a)/a>=FILE_SIZE_THRESHOLD&&i<FILE_SIZE_UNITS.length-1);return`${t.toFixed(r)} ${FILE_SIZE_UNITS[i]}`}return"0 B"},prettifyBadgeCount=(e,r=9)=>{if(0!==e)return e>=r?`${r}+`:String(e)},capitalizeFirst=e=>e.length>0?`${e[0].toUpperCase()}${e.slice(1)}`:"",toTitleCase=e=>e.replace(/\w\S*/g,(e=>e.charAt(0).toUpperCase()+e.substring(1).toLowerCase())),toSlug=e=>{const r=e.normalize("NFKD").replace(/[\u0300-\u036f]/g,"").toLowerCase().trim().replace(/['’]/g,"").replace(/[^a-z0-9]+/g,"-").replace(/-+/g,"-").replace(/^-|-$/g,"");if(0===r.length)throw new Error(encodeError(`Failed to slugify the string '${e}': the resulting slug is empty.`,ERRORS.UNABLE_TO_SLUGIFY_STRING));return r},truncateText=(e,r)=>e.length<=r?e:`${e.slice(0,r-3)}...`,maskMiddle=(e,r,t="...")=>e.length<=2*r?e:`${e.slice(0,r)}${t}${e.slice(-r)}`,applySubstitutions=(e,r={})=>e.replace(/{{(.*?)}}/g,((e,t)=>t in r?String(r[t]):e)),toMS=e=>{const{value:r,unit:t}=parseTimeString(e);switch(t){case"years":case"year":return r*ONE_YEAR_IN_MILLISECONDS;case"months":case"month":return r*ONE_MONTH_IN_MILLISECONDS;case"weeks":case"week":return r*ONE_WEEK_IN_MILLISECONDS;case"days":case"day":return r*ONE_DAY_IN_MILLISECONDS;case"hours":case"hour":return r*ONE_HOUR_IN_MILLISECONDS;case"minutes":case"minute":return r*ONE_MINUTE_IN_MILLISECONDS;case"seconds":case"second":return r*ONE_SECOND_IN_MILLISECONDS;case"milliseconds":case"millisecond":return r;default:throw new Error(encodeError(`The unit provided to the toMS function is invalid: "${t}". Received: ${e}`,ERRORS.INVALID_TIME_STRING))}},stringifyJSON=e=>{canJSONBeSerialized(e);try{const r=JSON.stringify(e);return validateJSONSerializationResult(e,r),r}catch(r){if(decodeError(r).code!==ERRORS.UNABLE_TO_SERIALIZE_JSON)throw new Error(encodeError(`Failed to stringify the JSON value '${e}': ${extractMessage(r)}`,ERRORS.UNABLE_TO_SERIALIZE_JSON));throw r}},stringifyJSONDeterministically=e=>{canJSONBeSerialized(e);try{return stringifyJSON(sortJSONObjectKeys(e))}catch(r){if(decodeError(r).code!==ERRORS.UNABLE_TO_SERIALIZE_JSON)throw new Error(encodeError(`Failed to stringify the JSON value deterministically '${e}': ${extractMessage(r)}`,ERRORS.UNABLE_TO_SERIALIZE_JSON));throw r}},parseJSON=e=>{canJSONBeDeserialized(e);try{const r=JSON.parse(e);return validateJSONDeserializationResult(e,r),r}catch(r){if(decodeError(r).code!==ERRORS.UNABLE_TO_DESERIALIZE_JSON)throw new Error(encodeError(`Failed to parse the JSON value '${e}': ${extractMessage(r)}`,ERRORS.UNABLE_TO_DESERIALIZE_JSON));throw r}},createDeepClone=e=>{try{return parseJSON(stringifyJSON(e))}catch(r){throw new Error(encodeError(`Failed to create a deep clone of the value '${e}': ${extractMessage(r)}`,ERRORS.UNABLE_TO_CREATE_DEEP_CLONE))}},pruneJSON=e=>{if(null==e)return null;if(Array.isArray(e)){const r=e.map((e=>pruneJSON(e))).filter((e=>null!=e&&(Array.isArray(e)?e.length>0:!isObjectValid(e,!0)||Object.keys(e).length>0)));return r.length>0?r:null}if(isObjectValid(e,!0)){const r={};return Object.entries(e).forEach((([e,t])=>{const i=pruneJSON(t);null!=i&&(Array.isArray(i)&&0===i.length||isObjectValid(i,!0)&&!isObjectValid(i)||(r[e]=i))})),Object.keys(r).length>0?r:null}return e};export{prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON};

package/dist/transformers/types.d.ts

@@ -1,15 +1,8 @@
-/**
- * JSON Value
- * A value that can be represented in JSON format.
- */
-type IJSONValue = string | number | boolean | null | IJSONValue[] | {
-    [key: string]: IJSONValue;
-};
 /**
  * Number Format Configuration
  * The configuration that will be used to prettify a number.
  */
-type INumberFormatConfig = {
+export type INumberFormatConfig = {
     minimumFractionDigits: number;
     maximumFractionDigits: number;
     prefix: string;
@@ -27,12 +20,12 @@ type INumberFormatConfig = {
  * - datetime-medium: Apr 29, 1453, 12:00:00 AM
  * - datetime-long: Friday, April 29th, 1453 at 12:00:00 AM
  */
-type IDateTemplate = 'date-short' | 'date-medium' | 'date-long' | 'time-short' | 'time-medium' | 'datetime-short' | 'datetime-medium' | 'datetime-long';
+export type IDateTemplate = 'date-short' | 'date-medium' | 'date-long' | 'time-short' | 'time-medium' | 'datetime-short' | 'datetime-medium' | 'datetime-long';
 /**
  * Date Template Configs
  * The options that will be combined in order to provide a format that can meet any requirement.
  */
-type IDateTemplateConfigs = {
+export type IDateTemplateConfigs = {
     [key in IDateTemplate]: {
         localeMatcher?: 'best fit' | 'lookup' | undefined;
         weekday?: 'long' | 'short' | 'narrow' | undefined;
@@ -49,4 +42,20 @@ type IDateTemplateConfigs = {
         timeZone?: string | undefined;
     };
 };
-export type { IJSONValue, INumberFormatConfig, IDateTemplate, IDateTemplateConfigs };
+/**
+ * Time String
+ * The following types were extracted from the 'ms' package, which is a popular library for parsing
+ * and formatting time durations. For more information, please refer to the original source:
+ * https://github.com/vercel/ms
+ */
+type IYears = 'years' | 'year';
+type IMonths = 'months' | 'month';
+type IWeeks = 'weeks' | 'week';
+type IDays = 'days' | 'day';
+type IHours = 'hours' | 'hour';
+type IMinutes = 'minutes' | 'minute';
+type ISeconds = 'seconds' | 'second';
+type IMilliseconds = 'milliseconds' | 'millisecond';
+export type IUnit = IYears | IMonths | IWeeks | IDays | IHours | IMinutes | ISeconds | IMilliseconds;
+export type ITimeString = `${number} ${IUnit}`;
+export {};

package/dist/transformers/utils.d.ts

@@ -1,21 +1,33 @@
-import { INumberFormatConfig } from './types.js';
+import { INumberFormatConfig, ITimeString } from './types.js';
 /**
  * Builds the object that will be passed to the number formatting function.
- * @param config?
- * @returns INumberFormatConfig
+ * @param config? The optional configuration object for number formatting.
+ * @returns The configuration object for number formatting with default values applied.
  */
-declare const buildNumberFormatConfig: (config?: Partial<INumberFormatConfig>) => INumberFormatConfig;
+export declare const buildNumberFormatConfig: (config?: Partial<INumberFormatConfig>) => INumberFormatConfig;
 /**
  * Creates an instance of Date based on a value.
- * @param value
- * @returns Date
+ * @param value The value to create a Date instance from. It can be a Date object, a timestamp, or a date string.
+ * @returns A Date instance.
  */
-declare const getDateInstance: (value: Date | number | string) => Date;
+export declare const getDateInstance: (value: Date | number | string) => Date;
+/**
+ * Parses a time string and returns an object containing the value and the unit.
+ * @param str The time string to parse.
+ * @returns The parsed time string as an object containing the value and the unit.
+ * @throws
+ * - INVALID_TIME_STRING: if the provided time string is not a valid string.
+ * - INVALID_TIME_STRING: if the chunks do not match the expected format.
+ * - INVALID_TIME_STRING: if the value is not a valid positive integer.
+ */
+export declare const parseTimeString: (str: ITimeString) => {
+    value: number;
+    unit: string;
+};
 /**
  * Recursively sorts the keys of a JSON object. If the value is not an object or an array, it
  * returns the value as is.
- * @param val
- * @returns unknown
+ * @param val The value to sort. It can be an object, an array, or any other type.
+ * @returns The value with sorted keys if it's an object, or the original value otherwise.
  */
-declare const sortJSONObjectKeys: (val: unknown) => unknown;
-export { buildNumberFormatConfig, getDateInstance, sortJSONObjectKeys };
+export declare const sortJSONObjectKeys: (val: unknown) => unknown;

package/dist/transformers/utils.js

@@ -1 +1 @@
-import{isArrayValid,isObjectValid}from"../validations/index.js";const buildNumberFormatConfig=(i={})=>({minimumFractionDigits:i.minimumFractionDigits??0,maximumFractionDigits:i.maximumFractionDigits??2,prefix:i.prefix??"",suffix:i.suffix??""}),getDateInstance=i=>i instanceof Date?i:new Date(i),sortJSONObjectKeys=i=>isArrayValid(i)?i.map(sortJSONObjectKeys):isObjectValid(i)?Object.keys(i).sort().reduce(((t,e)=>({...t,[e]:sortJSONObjectKeys(i[e])})),{}):i;export{buildNumberFormatConfig,getDateInstance,sortJSONObjectKeys};
+import{isArrayValid,isObjectValid}from"../validations/index.js";import{validateTimeStringChunks,validateTimeStringType,validateTimeStringValue}from"./validations.js";export const buildNumberFormatConfig=(i={})=>({minimumFractionDigits:i.minimumFractionDigits??0,maximumFractionDigits:i.maximumFractionDigits??2,prefix:i.prefix??"",suffix:i.suffix??""});export const getDateInstance=i=>i instanceof Date?i:new Date(i);export const parseTimeString=i=>{validateTimeStringType(i);const t=i.split(" ");validateTimeStringChunks(t);const e=Number(t[0]);return validateTimeStringValue(e),{value:e,unit:t[1]}};export const sortJSONObjectKeys=i=>isArrayValid(i)?i.map(sortJSONObjectKeys):isObjectValid(i)?Object.keys(i).sort().reduce(((t,e)=>({...t,[e]:sortJSONObjectKeys(i[e])})),{}):i;

package/dist/transformers/validations.d.ts

@@ -1,31 +1,52 @@
+import { ITimeString } from './types.js';
+/**
+ * Ensures a provided time string is valid and can be parsed by the toMS function.
+ * @param str The time string to validate.
+ * @throws
+ * - INVALID_TIME_STRING: if the provided time string is not a valid string.
+ */
+export declare const validateTimeStringType: (str: ITimeString) => void;
+/**
+ * Ensures the chunks obtained from splitting a time string are valid and can be parsed by the toMS function.
+ * @param chunks The chunks obtained from splitting a time string.
+ * @throws
+ * - INVALID_TIME_STRING: if the chunks do not match the expected format.
+ */
+export declare const validateTimeStringChunks: (chunks: string[]) => void;
+/**
+ * Ensures the value obtained from a time string is a valid positive integer that can be parsed by the toMS function.
+ * @param value The value to validate.
+ * @throws
+ * - INVALID_TIME_STRING: if the value is not a valid positive integer.
+ */
+export declare const validateTimeStringValue: (value: number) => void;
 /**
  * Checks if a JSON value can be serialized (JSON.stringify).
- * @param value
+ * @param value The value to check for JSON serialization. It should be an object or an array.
  * @throws
  * - UNSUPPORTED_DATA_TYPE: if the provided value is not an object or an array
  */
-declare const canJSONBeSerialized: (value: unknown) => void;
+export declare const canJSONBeSerialized: (value: unknown) => void;
 /**
  * Validates the result of a JSON serialization operation.
- * @param value
- * @param result
+ * @param value The original value that was attempted to be serialized.
+ * @param result The result of the JSON.stringify operation.
  * @throws
  * - UNABLE_TO_SERIALIZE_JSON: if the result of JSON.stringify is not a valid string
  */
-declare const validateJSONSerializationResult: (value: unknown, result: unknown) => void;
+export declare const validateJSONSerializationResult: (value: unknown, result: unknown) => void;
 /**
  * Checks if a JSON value can be deserialized (JSON.parse).
- * @param value
+ * @param value The value to check for JSON deserialization.
  * @throws
  * - UNSUPPORTED_DATA_TYPE: if the provided value is not a non-empty string
  */
-declare const canJSONBeDeserialized: (value: string) => void;
+export declare const canJSONBeDeserialized: (value: string) => void;
 /**
  * Validates the result of a JSON deserialization operation (JSON.parse).
- * @param value
- * @param result
+ * @param value The original value that was attempted to be deserialized.
+ * @param result The result of the JSON.parse operation.
  * @throws
  * - UNABLE_TO_DESERIALIZE_JSON: if the result of JSON.parse is not a valid object or array
  */
-declare const validateJSONDeserializationResult: (value: string, result: unknown) => void;
-export { canJSONBeSerialized, validateJSONSerializationResult, canJSONBeDeserialized, validateJSONDeserializationResult, };
+export declare const validateJSONDeserializationResult: (value: string, result: unknown) => void;

package/dist/transformers/validations.js

@@ -1 +1 @@
-import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isArrayValid,isObjectValid}from"../validations/index.js";const canJSONBeSerialized=e=>{if(!isObjectValid(e,!0)&&!isArrayValid(e,!0))throw new Error(encodeError(`The JSON value must be an object or an array in order to be stringified. Received: ${e}`,ERRORS.UNSUPPORTED_DATA_TYPE))},validateJSONSerializationResult=(e,r)=>{if("string"!=typeof r||!r.length)throw new Error(encodeError(`Stringifying the JSON value '${e}' produced an invalid result: ${r}.`,ERRORS.UNABLE_TO_SERIALIZE_JSON))},canJSONBeDeserialized=e=>{if("string"!=typeof e||!e.length)throw new Error(encodeError(`The JSON value must be a non-empty string in order to be parsed. Received: ${e}`,ERRORS.UNSUPPORTED_DATA_TYPE))},validateJSONDeserializationResult=(e,r)=>{if(!isObjectValid(r,!0)&&!isArrayValid(r,!0))throw new Error(encodeError(`Parsing the JSON value '${e}' produced an invalid result: ${r}.`,ERRORS.UNABLE_TO_DESERIALIZE_JSON))};export{canJSONBeSerialized,validateJSONSerializationResult,canJSONBeDeserialized,validateJSONDeserializationResult};
+import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isArrayValid,isIntegerValid,isObjectValid,isStringValid}from"../validations/index.js";export const validateTimeStringType=e=>{if(!isStringValid(e,5,100))throw new Error(encodeError(`The provided time string is invalid, it must be a string with length between 5 and 100. Received: ${e}`,ERRORS.INVALID_TIME_STRING))};export const validateTimeStringChunks=e=>{if(2!==e.length)throw new Error(encodeError(`The format of the provided time string is invalid, it must match the expected format {value} {unit}. For example: '2 days'. Received: ${JSON.stringify(e)}`,ERRORS.INVALID_TIME_STRING))};export const validateTimeStringValue=e=>{if(!isIntegerValid(e,1))throw new Error(encodeError(`The value of the provided time string is invalid, it must be a positive integer. Received: ${e}`,ERRORS.INVALID_TIME_STRING))};export const canJSONBeSerialized=e=>{if(!isObjectValid(e,!0)&&!isArrayValid(e,!0))throw new Error(encodeError(`The JSON value must be an object or an array in order to be stringified. Received: ${e}`,ERRORS.UNSUPPORTED_DATA_TYPE))};export const validateJSONSerializationResult=(e,r)=>{if("string"!=typeof r||!r.length)throw new Error(encodeError(`Stringifying the JSON value '${e}' produced an invalid result: ${r}.`,ERRORS.UNABLE_TO_SERIALIZE_JSON))};export const canJSONBeDeserialized=e=>{if("string"!=typeof e||!e.length)throw new Error(encodeError(`The JSON value must be a non-empty string in order to be parsed. Received: ${e}`,ERRORS.UNSUPPORTED_DATA_TYPE))};export const validateJSONDeserializationResult=(e,r)=>{if(!isObjectValid(r,!0)&&!isArrayValid(r,!0))throw new Error(encodeError(`Parsing the JSON value '${e}' produced an invalid result: ${r}.`,ERRORS.UNABLE_TO_DESERIALIZE_JSON))};

package/dist/utils/index.d.ts

@@ -2,52 +2,52 @@ import { IUUIDVersion } from '../shared/types.js';
 import { IFilterByQueryOptions, ISortDirection } from './types.js';
 /**
  * Generates a UUID based on a version.
- * @param version
- * @returns string
+ * @param version The version of the UUID to be generated.
+ * @returns A UUID string of the specified version.
  */
 declare const generateUUID: (version: IUUIDVersion) => string;
 /**
  * Generates a string from randomly picked characters based on the length.
- * @param length
- * @param characters?
- * @returns string
+ * @param length The length of the random string to be generated.
+ * @param characters? A string of characters to pick from when generating the random string. Defaults to 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'.
+ * @returns A randomly generated string of the specified length.
  */
 declare const generateRandomString: (length: number, characters?: string) => string;
 /**
  * Generates a random number (decimal) constrained by the range.
- * @param min
- * @param max
- * @returns number
+ * @param min The minimum value of the range.
+ * @param max The maximum value of the range.
+ * @returns A randomly generated decimal number within the specified range.
  */
 declare const generateRandomFloat: (min: number, max: number) => number;
 /**
  * Generates a random number (integer) constrained by the range.
- * @param min
- * @param max
- * @returns number
+ * @param min The minimum value of the range.
+ * @param max The maximum value of the range.
+ * @returns A randomly generated integer number within the specified range.
  */
 declare const generateRandomInteger: (min: number, max: number) => number;
 /**
  * Generates a sequence of numbers within a range based on a number of steps.
- * @param start
- * @param stop
- * @param step?
- * @returns number[]
+ * @param start The starting value of the sequence.
+ * @param stop The ending value of the sequence.
+ * @param step? The step value to increment the sequence. Defaults to 1.
+ * @returns An array of numbers representing the sequence.
  */
 declare const generateSequence: (start: number, stop: number, step?: number) => number[];
 /**
  * Sorts a list of primitive values based on their type and a sort direction.
- * @param direction
- * @returns <T extends string | number>(a: T, b: T): number
+ * @param direction The direction to sort the values.
+ * @returns A number indicating the sort order based on the primitive type.
  * @throws
  * - MIXED_OR_UNSUPPORTED_DATA_TYPES: if the values are mixed or are different to string | number
  */
 declare const sortPrimitives: (direction: ISortDirection) => <T extends string | number>(a: T, b: T) => number;
 /**
  * Sorts a list of record values by key based on their type and a sort direction.
- * @param key
- * @param direction
- * @returns <T extends string | number>(a: T, b: T): number
+ * @param key The key of the record to sort by.
+ * @param direction The direction to sort the values.
+ * @returns A number indicating the sort order based on the primitive type.
  * @throws
  * - MIXED_OR_UNSUPPORTED_DATA_TYPES: if the values are mixed or are different to string | number
  */
@@ -55,27 +55,27 @@ declare const sortRecords: (key: string, direction: ISortDirection) => <T extend
 /**
  * Creates a shallow copy of the input array and shuffles it, using a version of the Fisher-Yates
  * algorithm.
- * @param input
- * @returns Array<T>
+ * @param input The array to be shuffled.
+ * @returns A new array with the values of the input array in a random order.
  * @throws
  * - INVALID_OR_EMPTY_ARRAY: if the input is not array or it is empty
  */
 declare const shuffleArray: <T>(input: Array<T>) => Array<T>;
 /**
  * Splits an array into smaller arrays (batches) of a given size.
- * @param items
- * @param batchSize
- * @returns Array<T[]>
+ * @param items The array to be split into batches.
+ * @param batchSize The size of each batch.
+ * @returns An array of arrays, where each inner array is a batch of the specified size.
  * @throws
  * - INVALID_BATCH_SIZE: if the batch size is not a valid integer greater than 0
  */
-export declare const splitArrayIntoBatches: <T>(items: T[], batchSize: number) => Array<T[]>;
+declare const splitArrayIntoBatches: <T>(items: T[], batchSize: number) => Array<T[]>;
 /**
  * Picks a list of properties from an object and returns a new object (shallow) with the provided
  * keys.
- * @param input
- * @param propKeys
- * @returns Pick<T, K>
+ * @param input The object from which to pick properties.
+ * @param propKeys The keys of the properties to pick.
+ * @returns A new object containing only the picked properties.
  * @throws
  * - INVALID_OR_EMPTY_OBJECT: if the input is not a valid object or it is empty
  * - INVALID_OR_EMPTY_ARRAY: if the keys to be picked are not a valid array or it is empty
@@ -84,19 +84,19 @@ declare const pickProps: <T extends Record<string, any>, K extends keyof T>(inpu
 /**
  * Omits a list of properties from an object and returns a new object (shallow) with only those
  * keys that weren't omitted
- * @param input
- * @param propKeys
- * @returns Omit<T, K>
+ * @param input The object from which to omit properties.
+ * @param propKeys The keys of the properties to omit.
+ * @returns A new object containing only the properties that were not omitted.
  * @throws
  * - INVALID_OR_EMPTY_OBJECT: if the input is not a valid object or it is empty
  * - INVALID_OR_EMPTY_ARRAY: if the keys to be omitted are not a valid array or it is empty
  */
 declare const omitProps: <T extends Record<string, any>, K extends keyof T>(input: T, propKeys: K[]) => Omit<T, K>;
 /**
- * Compares two objects or arrays deeply and returns true if they are equals.
- * @param a
- * @param b
- * @returns boolean
+ * Compares two objects or arrays deeply and returns true if they are equal.
+ * @param a The first object or array to compare.
+ * @param b The second object or array to compare.
+ * @returns A boolean indicating whether the two values are equal.
  * @throws
  * - UNSUPPORTED_DATA_TYPE: if any of the values isn't an object or an array
  * - UNABLE_TO_SERIALIZE_JSON: if any of the values contains data that cannot be serialized
@@ -106,25 +106,24 @@ declare const isEqual: (a: Record<string, any> | Array<any>, b: Record<string, a
  * Filters an array of primitives based on a given query and returns a shallow copy.
  * @IMPORTANT Providing the queryProp makes the query very efficient as it only attempts to match
  * the value of that property, instead of the whole item.
- * @param items
- * @param query
- * @param options?
- * @returns T[]
+ * @param items The array of items to be filtered by the query.
+ * @param query The query string to filter the items by.
+ * @param options? The options to filter the items by query.
+ * @returns A new array containing the items that match the query based on the provided options.
  */
 declare const filterByQuery: <T>(items: T[], query: string, options?: IFilterByQueryOptions<T>) => T[];
 /**
  * Creates an asynchronous delay that resolves once the provided seconds have passed.
- * @param seconds
- * @returns Promise<void>
+ * @param seconds The number of seconds to delay before the promise resolves.
+ * @returns A promise that resolves after the specified number of seconds has passed.
  */
 declare const delay: (seconds: number) => Promise<void>;
 /**
  * Executes an asynchronous function persistently, retrying on error with incremental delays
  * defined in retryScheduleDuration (seconds).
- * @param func
- * @param args?
- * @param retryScheduleDuration?
- * @returns Promise<T>
+ * @param func The asynchronous function to be executed persistently.
+ * @param retryScheduleDuration? An array of numbers representing the delay (in seconds) between each retry attempt. Defaults to [3, 5].
+ * @returns A promise that resolves with the result of the asynchronous function or rejects with the last encountered error.
  */
 declare const retryAsyncFunction: <T>(func: () => Promise<T>, retryScheduleDuration?: number[]) => Promise<T>;
-export { generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, isEqual, filterByQuery, delay, retryAsyncFunction, };
+export { type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, splitArrayIntoBatches, pickProps, omitProps, isEqual, filterByQuery, delay, retryAsyncFunction, };

package/dist/utils/index.js

@@ -1 +1 @@
-import{v4 as uuidv4,v7 as uuidv7}from"uuid";import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isIntegerValid}from"../validations/index.js";import{stringifyJSONDeterministically}from"../transformers/index.js";import{canArrayBeShuffled,validateObjectAndKeys}from"./validations.js";import{buildNormalizedQueryTokens}from"./transformers.js";import{filterItemsByQueryTokens}from"./utils.js";const generateUUID=e=>7===e?uuidv7():uuidv4(),generateRandomString=(e,r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")=>{let t="",n=0;for(;n<e;)t+=r.charAt(Math.floor(Math.random()*r.length)),n+=1;return t},generateRandomFloat=(e,r)=>{const t=Math.random()*(r-e+1)+e;return t>r?r:t},generateRandomInteger=(e,r)=>Math.floor(generateRandomFloat(e,r)),generateSequence=(e,r,t=1)=>Array.from({length:(r-e)/t+1},((r,n)=>e+n*t)),__sortStringValues=(e,r,t)=>{const n=e.toLocaleLowerCase(),o=r.toLocaleLowerCase();return n>o?"asc"===t?1:-1:o>n?"asc"===t?-1:1:0},__sortNumberValues=(e,r,t)=>"asc"===t?e-r:r-e,sortPrimitives=e=>(r,t)=>{if("string"==typeof r&&"string"==typeof t)return __sortStringValues(r,t,e);if("number"==typeof r&&"number"==typeof t)return __sortNumberValues(r,t,e);throw new Error(encodeError(`Unable to sort list of primitive values as they can only be string | number and must not be mixed. Received: ${typeof r}, ${typeof t}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},sortRecords=(e,r)=>(t,n)=>{if("string"==typeof t[e]&&"string"==typeof n[e])return __sortStringValues(t[e],n[e],r);if("number"==typeof t[e]&&"number"==typeof n[e])return __sortNumberValues(t[e],n[e],r);throw new Error(encodeError(`Unable to sort list of record values as they can only be string | number and must not be mixed. Received: ${typeof t[e]}, ${typeof n[e]}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},shuffleArray=e=>{canArrayBeShuffled(e);const r=e.slice();for(let e=r.length-1;e>0;e-=1){const t=Math.floor(Math.random()*(e+1));[r[e],r[t]]=[r[t],r[e]]}return r};export const splitArrayIntoBatches=(e,r)=>{if(!e.length)return[];if(!isIntegerValid(r,1))throw new Error(encodeError(`In order to split an array into batches, the batch size must be an integer greater than 0. Received: ${r}`,ERRORS.INVALID_BATCH_SIZE));const t=[];for(let n=0;n<e.length;n+=r)t.push(e.slice(n,n+r));return t};const pickProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(r.map((r=>[r,e[r]])))),omitProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(Object.entries(e).filter((([e])=>!r.includes(e))))),isEqual=(e,r)=>stringifyJSONDeterministically(e)===stringifyJSONDeterministically(r),filterByQuery=(e,r,t)=>{if(!e.length||!r)return e;const n=buildNormalizedQueryTokens(r);if(!n.length)return e;const o=filterItemsByQueryTokens(e,n,t?.queryProp);return"number"==typeof t?.limit?o.slice(0,t.limit):o},delay=e=>new Promise((r=>{setTimeout(r,Math.round(1e3*e))})),retryAsyncFunction=async(e,r=[3,5])=>{try{return await e()}catch(t){if(0===r.length)throw t;return await delay(r[0]),retryAsyncFunction(e,r.slice(1))}};export{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,isEqual,filterByQuery,delay,retryAsyncFunction};
+import{v4 as uuidv4,v7 as uuidv7}from"uuid";import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isIntegerValid}from"../validations/index.js";import{stringifyJSONDeterministically}from"../transformers/index.js";import{canArrayBeShuffled,validateObjectAndKeys}from"./validations.js";import{buildNormalizedQueryTokens}from"./transformers.js";import{filterItemsByQueryTokens}from"./utils.js";const generateUUID=e=>7===e?uuidv7():uuidv4(),generateRandomString=(e,r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")=>{let t="",n=0;for(;n<e;)t+=r.charAt(Math.floor(Math.random()*r.length)),n+=1;return t},generateRandomFloat=(e,r)=>{const t=Math.random()*(r-e+1)+e;return t>r?r:t},generateRandomInteger=(e,r)=>Math.floor(generateRandomFloat(e,r)),generateSequence=(e,r,t=1)=>Array.from({length:(r-e)/t+1},((r,n)=>e+n*t)),__sortStringValues=(e,r,t)=>{const n=e.toLocaleLowerCase(),o=r.toLocaleLowerCase();return n>o?"asc"===t?1:-1:o>n?"asc"===t?-1:1:0},__sortNumberValues=(e,r,t)=>"asc"===t?e-r:r-e,sortPrimitives=e=>(r,t)=>{if("string"==typeof r&&"string"==typeof t)return __sortStringValues(r,t,e);if("number"==typeof r&&"number"==typeof t)return __sortNumberValues(r,t,e);throw new Error(encodeError(`Unable to sort list of primitive values as they can only be string | number and must not be mixed. Received: ${typeof r}, ${typeof t}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},sortRecords=(e,r)=>(t,n)=>{if("string"==typeof t[e]&&"string"==typeof n[e])return __sortStringValues(t[e],n[e],r);if("number"==typeof t[e]&&"number"==typeof n[e])return __sortNumberValues(t[e],n[e],r);throw new Error(encodeError(`Unable to sort list of record values as they can only be string | number and must not be mixed. Received: ${typeof t[e]}, ${typeof n[e]}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},shuffleArray=e=>{canArrayBeShuffled(e);const r=e.slice();for(let e=r.length-1;e>0;e-=1){const t=Math.floor(Math.random()*(e+1));[r[e],r[t]]=[r[t],r[e]]}return r},splitArrayIntoBatches=(e,r)=>{if(!e.length)return[];if(!isIntegerValid(r,1))throw new Error(encodeError(`In order to split an array into batches, the batch size must be an integer greater than 0. Received: ${r}`,ERRORS.INVALID_BATCH_SIZE));const t=[];for(let n=0;n<e.length;n+=r)t.push(e.slice(n,n+r));return t},pickProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(r.map((r=>[r,e[r]])))),omitProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(Object.entries(e).filter((([e])=>!r.includes(e))))),isEqual=(e,r)=>stringifyJSONDeterministically(e)===stringifyJSONDeterministically(r),filterByQuery=(e,r,t)=>{if(!e.length||!r)return e;const n=buildNormalizedQueryTokens(r);if(!n.length)return e;const o=filterItemsByQueryTokens(e,n,t?.queryProp);return"number"==typeof t?.limit?o.slice(0,t.limit):o},delay=e=>new Promise((r=>{setTimeout(r,Math.round(1e3*e))})),retryAsyncFunction=async(e,r=[3,5])=>{try{return await e()}catch(t){if(0===r.length)throw t;return await delay(r[0]),retryAsyncFunction(e,r.slice(1))}};export{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,splitArrayIntoBatches,pickProps,omitProps,isEqual,filterByQuery,delay,retryAsyncFunction};

package/dist/utils/transformers.d.ts

@@ -1,13 +1,12 @@
 /**
  * Builds an array of normalized query tokens from a given query string.
- * @param query
- * @returns string[]
+ * @param query The query string to be normalized and tokenized.
+ * @returns A normalized array of query tokens.
  */
-declare const buildNormalizedQueryTokens: (query: string) => string[];
+export declare const buildNormalizedQueryTokens: (query: string) => string[];
 /**
  * Stringifies a value so it can be compared in a case-insensitive manner.
- * @param value
- * @returns string
+ * @param value The value to be normalized.
+ * @returns A normalized string representation of the value.
  */
-declare const normalizeItemValue: (value: unknown) => string;
-export { buildNormalizedQueryTokens, normalizeItemValue };
+export declare const normalizeItemValue: (value: unknown) => string;

package/dist/utils/transformers.js

@@ -1 +1 @@
-import{isArrayValid,isObjectValid}from"../validations/index.js";const buildNormalizedQueryTokens=e=>e.toLowerCase().split(" ").filter(Boolean),normalizeItemValue=e=>"string"==typeof e?e.toLowerCase():isObjectValid(e,!0)?Object.values(e).map(normalizeItemValue).join(" "):isArrayValid(e,!0)?e.map(normalizeItemValue).join(" "):null!=e?String(e).toLowerCase():"";export{buildNormalizedQueryTokens,normalizeItemValue};
+import{isArrayValid,isObjectValid}from"../validations/index.js";export const buildNormalizedQueryTokens=e=>e.toLowerCase().split(" ").filter(Boolean);export const normalizeItemValue=e=>"string"==typeof e?e.toLowerCase():isObjectValid(e,!0)?Object.values(e).map(normalizeItemValue).join(" "):isArrayValid(e,!0)?e.map(normalizeItemValue).join(" "):null!=e?String(e).toLowerCase():"";

package/dist/utils/types.d.ts

@@ -1,6 +1,5 @@
-type ISortDirection = 'asc' | 'desc';
-type IFilterByQueryOptions<T> = {
+export type ISortDirection = 'asc' | 'desc';
+export type IFilterByQueryOptions<T> = {
     queryProp?: keyof T;
     limit?: number;
 };
-export type { ISortDirection, IFilterByQueryOptions, };

package/dist/utils/utils.d.ts

@@ -1,9 +1,8 @@
 /**
  * Applies the filter to the items based on the query tokens and returns a filtered list.
- * @param items
- * @param queryTokens
- * @param queryProp
- * @returns T[]
+ * @param items The list of items to be filtered.
+ * @param queryTokens The array of normalized query tokens to filter the items by.
+ * @param queryProp The property of the item to filter by, if not provided, the whole item will be used for filtering.
+ * @returns A filtered array of items that match the query tokens.
  */
-declare const filterItemsByQueryTokens: <T>(items: T[], queryTokens: string[], queryProp: keyof T | undefined) => T[];
-export { filterItemsByQueryTokens };
+export declare const filterItemsByQueryTokens: <T>(items: T[], queryTokens: string[], queryProp: keyof T | undefined) => T[];

package/dist/utils/utils.js

@@ -1 +1 @@
-import{normalizeItemValue}from"./transformers.js";const filterItemsByQueryTokens=(e,r,t)=>e.filter((e=>{const o=normalizeItemValue("string"==typeof t?e[t]:e);return r.some((e=>o.includes(e)))}));export{filterItemsByQueryTokens};
+import{normalizeItemValue}from"./transformers.js";export const filterItemsByQueryTokens=(e,r,t)=>e.filter((e=>{const o=normalizeItemValue("string"==typeof t?e[t]:e);return r.some((e=>o.includes(e)))}));

package/dist/utils/validations.d.ts

@@ -4,14 +4,13 @@
  * @throws
  * - INVALID_OR_EMPTY_ARRAY: If the input is not an array or has less than 2 items.
  */
-declare const canArrayBeShuffled: (input: unknown[]) => void;
+export declare const canArrayBeShuffled: (input: unknown[]) => void;
 /**
  * Validates the input object and the keys to be picked/omitted.
- * @param input
- * @param propKeys
+ * @param input The object to be validated.
+ * @param propKeys The keys to be picked/omitted, which must be a non-empty array of strings.
  * @throws
  * - INVALID_OR_EMPTY_OBJECT: If the input is not a valid object or is empty.
  * - INVALID_OR_EMPTY_ARRAY: If the keys are not a valid array or are empty.
  */
-declare const validateObjectAndKeys: (input: unknown, propKeys: unknown) => void;
-export { canArrayBeShuffled, validateObjectAndKeys };
+export declare const validateObjectAndKeys: (input: unknown, propKeys: unknown) => void;

package/dist/utils/validations.js

@@ -1 +1 @@
-import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isArrayValid,isObjectValid}from"../validations/index.js";const canArrayBeShuffled=r=>{if(!Array.isArray(r)||r.length<=1)throw new Error(encodeError("For an array to be shuffled it must contain at least 2 items.",ERRORS.INVALID_OR_EMPTY_ARRAY))},validateObjectAndKeys=(r,e)=>{if(!isObjectValid(r))throw new Error(encodeError("The input must be a valid and non-empty object.",ERRORS.INVALID_OR_EMPTY_OBJECT));if(!isArrayValid(e))throw new Error(encodeError("The keys must be a valid and non-empty array of strings.",ERRORS.INVALID_OR_EMPTY_ARRAY))};export{canArrayBeShuffled,validateObjectAndKeys};
+import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isArrayValid,isObjectValid}from"../validations/index.js";export const canArrayBeShuffled=r=>{if(!Array.isArray(r)||r.length<=1)throw new Error(encodeError("For an array to be shuffled it must contain at least 2 items.",ERRORS.INVALID_OR_EMPTY_ARRAY))};export const validateObjectAndKeys=(r,e)=>{if(!isObjectValid(r))throw new Error(encodeError("The input must be a valid and non-empty object.",ERRORS.INVALID_OR_EMPTY_OBJECT));if(!isArrayValid(e))throw new Error(encodeError("The keys must be a valid and non-empty array of strings.",ERRORS.INVALID_OR_EMPTY_ARRAY))};

package/dist/validations/index.d.ts

@@ -1,80 +1,81 @@
 import { IUUIDVersion } from '../shared/types.js';
 /**
  * Verifies if a value is a valid string and its length is within a range (optional).
- * @param value
- * @param minLength?
- * @param maxLength?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param minLength? The minimum length of the string. If not provided, it will not check for a minimum length. Defaults to 1.
+ * @param maxLength? The maximum length of the string. If not provided, it will not check for a maximum length.
+ * @param disallowWhitespaceOnly? A boolean indicating whether strings that contain only whitespace should be considered invalid. Defaults to true.
+ * @returns A boolean indicating whether the value is a valid string and meets the length requirements (if provided).
  */
-declare const isStringValid: (value: unknown, minLength?: number, maxLength?: number) => value is string;
+export declare const isStringValid: (value: unknown, minLength?: number, maxLength?: number, disallowWhitespaceOnly?: boolean) => value is string;
 /**
  * Verifies if a value is a valid number and is within a range (optional). The minimum value
  * defaults to Number.MIN_SAFE_INTEGER (-9007199254740991) while the maximum value defaults to
  * Number.MAX_SAFE_INTEGER (9007199254740991).
- * @param value
- * @param min?
- * @param max?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param min? The minimum value. If not provided, it will default to Number.MIN_SAFE_INTEGER.
+ * @param max? The maximum value. If not provided, it will default to Number.MAX_SAFE_INTEGER.
+ * @returns A boolean indicating whether the value is a valid number and within the specified range.
  */
-declare const isNumberValid: (value: unknown, min?: number, max?: number) => value is number;
+export declare const isNumberValid: (value: unknown, min?: number, max?: number) => value is number;
 /**
  * Verifies if a value is a valid integer and is within a range (optional). If a range is not
  * provided, it will use the properties Number.MIN_SAFE_INTEGER & Number.MAX_SAFE_INTEGER.
- * @param value
- * @param min?
- * @param max?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param min? The minimum value. If not provided, it will default to Number.MIN_SAFE_INTEGER.
+ * @param max? The maximum value. If not provided, it will default to Number.MAX_SAFE_INTEGER.
+ * @returns A boolean indicating whether the value is a valid integer and within the specified range.
  */
-declare const isIntegerValid: (value: unknown, min?: number, max?: number) => value is number;
+export declare const isIntegerValid: (value: unknown, min?: number, max?: number) => value is number;
 /**
  * Verifies if a value is a valid unix timestamp in milliseconds. The smallest value is set for
  * the beginning of the Unix epoch (January 1st, 1970 - 14400000) while the largest value is based
  * on the numeric limit established by JavaScript (9007199254740991).
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid unix timestamp in milliseconds.
  */
-declare const isTimestampValid: (value: unknown) => value is number;
+export declare const isTimestampValid: (value: unknown) => value is number;
 /**
  * Verifies if a value is a valid numeric string.
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid numeric string.
  */
-declare const isNumeric: (value: string) => boolean;
+export declare const isNumeric: (value: string) => boolean;
 /**
  * Verifies if a value is an actual object. It also validates if it has keys (optional).
- * @param value
- * @param allowEmpty?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param allowEmpty? A boolean indicating whether empty objects are allowed. Defaults to false.
+ * @returns A boolean indicating whether the value is a valid object and meets the key requirements (if provided).
  */
-declare const isObjectValid: (value: unknown, allowEmpty?: boolean) => value is Record<string, any>;
+export declare const isObjectValid: (value: unknown, allowEmpty?: boolean) => value is Record<string, any>;
 /**
  * Verifies if a value is an array. It also validates if it has elements inside (optional).
- * @param value
- * @param allowEmpty?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param allowEmpty? A boolean indicating whether empty arrays are allowed. Defaults to false.
+ * @returns A boolean indicating whether the value is a valid array and meets the element requirements (if provided).
  */
-declare const isArrayValid: (value: unknown, allowEmpty?: boolean) => value is Array<any>;
+export declare const isArrayValid: (value: unknown, allowEmpty?: boolean) => value is Array<any>;
 /**
  * Verifies if a value is a valid email address.
  * Important: when providing forbiddenExtensions, ensure to include the dot (.) at the beginning.
  * For example, to forbid .con, use ['.con'].
- * @param value
- * @param forbiddenExtensions?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param forbiddenExtensions? An array of forbidden email extensions. Defaults to ['.con'].
+ * @returns A boolean indicating whether the value is a valid email address and does not have a forbidden extension.
  */
-declare const isEmailValid: (value: unknown, forbiddenExtensions?: string[]) => value is string;
+export declare const isEmailValid: (value: unknown, forbiddenExtensions?: string[]) => value is string;
 /**
  * Verifies if a slug meets the following requirements:
- * - Accepts any Alpha Characters (lower and upper case)
+ * - Accepts any lowercase alpha characters
  * - Accepts any digits
  * - Accepts - , . and/or _
  * - Meets a length range (Defaults to 2 - 16)
- * @param value
- * @param minLength?
- * @param maxLength?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param minLength? The minimum length of the slug. Defaults to 2.
+ * @param maxLength? The maximum length of the slug. Defaults to 16.
+ * @returns A boolean indicating whether the value is a valid slug.
  */
-declare const isSlugValid: (value: unknown, minLength?: number, maxLength?: number) => value is string;
+export declare const isSlugValid: (value: unknown, minLength?: number, maxLength?: number) => value is string;
 /**
  * Verifies if a password meets the following requirements:
  * - Meets a length range (Defaults to 8 - 2048)
@@ -82,58 +83,57 @@ declare const isSlugValid: (value: unknown, minLength?: number, maxLength?: numb
  * - At least one lowercase letter
  * - At least one number
  * - At least one special character
- * @param value
- * @param minLength?
- * @param maxLength?
- * @returns boolean
+ * @param value The value to be validated.
+ * @param minLength? The minimum length of the password. Defaults to 8.
+ * @param maxLength? The maximum length of the password. Defaults to 2048.
+ * @returns A boolean indicating whether the value is a valid password.
  */
-declare const isPasswordValid: (value: unknown, minLength?: number, maxLength?: number) => value is string;
+export declare const isPasswordValid: (value: unknown, minLength?: number, maxLength?: number) => value is string;
 /**
  * Verifies if a value has the correct OTP Secret Format.
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid OTP secret.
  */
-declare const isOTPSecretValid: (value: unknown) => value is string;
+export declare const isOTPSecretValid: (value: unknown) => value is string;
 /**
  * Verifies if a value has the correct OTP Token Format.
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid OTP token.
  */
-declare const isOTPTokenValid: (value: unknown) => value is string;
+export declare const isOTPTokenValid: (value: unknown) => value is string;
 /**
  * Verifies if a value has a correct JWT Format:
  * [Base64-URL Encoded Header].[Base64-URL Encoded Payload].[Signature]
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid JWT.
  */
-declare const isJWTValid: (value: unknown) => value is string;
+export declare const isJWTValid: (value: unknown) => value is string;
 /**
  * Verifies if a value has a valid Authorization Header format based on the RFC6750. Example:
  * Authorization: Bearer eyJhbGciOiJIUzI1NiIXVCJ9TJV...r7E20RMHrHDcEfxjoYZgeFONFh7HgQ
  * More info:
  * - https://stackoverflow.com/questions/33265812/best-http-authorization-header-type-for-jwt
  * - https://www.rfc-editor.org/rfc/rfc6750
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid Authorization header.
  */
-declare const isAuthorizationHeaderValid: (value: unknown) => value is string;
+export declare const isAuthorizationHeaderValid: (value: unknown) => value is string;
 /**
  * Verifies if a value complies with semantic versioning.
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid semantic version.
  */
-declare const isSemverValid: (value: unknown) => value is string;
+export declare const isSemverValid: (value: unknown) => value is string;
 /**
  * Verifies if a value is a valid URL.
- * @param value
- * @returns boolean
+ * @param value The value to be validated.
+ * @returns A boolean indicating whether the value is a valid URL.
  */
-declare const isURLValid: (value: unknown) => value is string;
+export declare const isURLValid: (value: unknown) => value is string;
 /**
  * Verifies if a value is a valid UUID and that it matches a specific version.
- * @param value
- * @param version
- * @returns boolean
+ * @param value The value to be validated.
+ * @param version The UUID version to be validated against.
+ * @returns A boolean indicating whether the value is a valid UUID of the specified version.
  */
-declare const isUUIDValid: (value: unknown, version: IUUIDVersion) => value is string;
-export { isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isNumeric, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid, };
+export declare const isUUIDValid: (value: unknown, version: IUUIDVersion) => value is string;

package/dist/validations/index.js

@@ -1 +1 @@
-import{version as uuidVersion,validate as uuidValidate}from"uuid";const isStringValid=(i,e,a)=>"string"==typeof i&&(void 0===e||i.length>=e)&&(void 0===a||i.length<=a),isNumberValid=(i,e=Number.MIN_SAFE_INTEGER,a=Number.MAX_SAFE_INTEGER)=>"number"==typeof i&&i>=e&&i<=a,isIntegerValid=(i,e,a)=>isNumberValid(i,e,a)&&Number.isInteger(i),isTimestampValid=i=>isIntegerValid(i,144e5),isNumeric=i=>"string"==typeof i&&/^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(i),isObjectValid=(i,e)=>null!==i&&"object"==typeof i&&!Array.isArray(i)&&(e||Object.keys(i).length>0),isArrayValid=(i,e)=>Array.isArray(i)&&(e||i.length>0),isEmailValid=(i,e=[".con"])=>{if(!isStringValid(i,5,200))return!1;const a=i.toLowerCase();return/^[a-z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/.test(a)&&!e.some((i=>a.endsWith(i)))},isSlugValid=(i,e=2,a=16)=>isStringValid(i,e,a)&&/^[a-zA-Z0-9\-._]+$/.test(i),isPasswordValid=(i,e=8,a=2048)=>isStringValid(i,e,a)&&/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[\W_])[A-Za-z\d\W_]+$/.test(i),isOTPSecretValid=i=>"string"==typeof i&&/^[0-9a-zA-Z]{16,64}$/.test(i),isOTPTokenValid=i=>"string"==typeof i&&/^[0-9]{6}$/.test(i),isJWTValid=i=>"string"==typeof i&&/^[A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}$/.test(i),isAuthorizationHeaderValid=i=>"string"==typeof i&&/^Bearer [A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}$/.test(i),isSemverValid=i=>"string"==typeof i&&/^[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}$/.test(i),isURLValid=i=>{if("string"!=typeof i)return!1;try{new URL(i);return!0}catch(i){return!1}},isUUIDValid=(i,e)=>"string"==typeof i&&uuidValidate(i)&&uuidVersion(i)===e;export{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isNumeric,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid};
+import{version as uuidVersion,validate as uuidValidate}from"uuid";export const isStringValid=(t,e=1,i,r=!0)=>"string"==typeof t&&(void 0===e||t.length>=e)&&(void 0===i||t.length<=i)&&(!r||t.trim().length>0);export const isNumberValid=(t,e=Number.MIN_SAFE_INTEGER,i=Number.MAX_SAFE_INTEGER)=>"number"==typeof t&&t>=e&&t<=i;export const isIntegerValid=(t,e,i)=>isNumberValid(t,e,i)&&Number.isInteger(t);export const isTimestampValid=t=>isIntegerValid(t,144e5);export const isNumeric=t=>"string"==typeof t&&/^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(t);export const isObjectValid=(t,e)=>null!==t&&"object"==typeof t&&!Array.isArray(t)&&(e||Object.keys(t).length>0);export const isArrayValid=(t,e)=>Array.isArray(t)&&(e||t.length>0);export const isEmailValid=(t,e=[".con"])=>{if(!isStringValid(t,5,200))return!1;const i=t.toLowerCase();return/^[a-z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/.test(i)&&!e.some((t=>i.endsWith(t)))};export const isSlugValid=(t,e=2,i=16)=>isStringValid(t,e,i)&&/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(t);export const isPasswordValid=(t,e=8,i=2048)=>isStringValid(t,e,i)&&/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[\W_])[A-Za-z\d\W_]+$/.test(t);export const isOTPSecretValid=t=>"string"==typeof t&&/^[0-9a-zA-Z]{16,64}$/.test(t);export const isOTPTokenValid=t=>"string"==typeof t&&/^[0-9]{6}$/.test(t);export const isJWTValid=t=>"string"==typeof t&&/^[A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}$/.test(t);export const isAuthorizationHeaderValid=t=>"string"==typeof t&&/^Bearer [A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}\.[A-Za-z0-9-_]{2,1000}$/.test(t);export const isSemverValid=t=>"string"==typeof t&&/^[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}$/.test(t);export const isURLValid=t=>{if("string"!=typeof t)return!1;try{new URL(t);return!0}catch(t){return!1}};export const isUUIDValid=(t,e)=>"string"==typeof t&&uuidValidate(t)&&uuidVersion(t)===e;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-utils-kit",
-  "version": "1.0.16",
+  "version": "1.1.1",
   "description": "The web-utils-kit package provides a collection of well-tested and thoroughly documented utility functions for various web development needs. Each function adheres to a strict coding style and best practices to ensure consistency and maintainability.",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "vitest": "3.2.4"
   },
   "dependencies": {
-    "error-message-utils": "1.1.6",
+    "error-message-utils": "1.2.1",
     "uuid": "11.0.3"
   }
 }