js-utils-kit 0.5.5 → 1.0.0

package/dist/file/index.d.ts

@@ -1,75 +0,0 @@
-import { ArchiverOptions } from 'archiver';
-export { ArchiverOptions } from 'archiver';
-
-/**
- * Supported archive formats.
- */
-type ArchiveFormat = 'zip' | 'tar';
-/**
- * Configuration options.
- */
-interface CreateArchiveOptions {
-    /**
-     * Archive format to use {@link ArchiveFormat}.
-     */
-    format: ArchiveFormat;
-    /**
-     * Path to the source directory that should be archived.
-     */
-    source: string;
-    /**
-     * Destination file path where the archive will be written
-     * @example
-     *  - For `zip` format: `dist.zip`
-     *  - For `tar` format: `dist.tar`
-     */
-    destination: string;
-    /**
-     * Additional options passed directly to the archiver library. See {@link ArchiverOptions}.
-     */
-    options?: ArchiverOptions;
-    /**
-     * Optional flag to enable internal logging. Useful for CLI mode.
-     */
-    log?: boolean;
-    /**
-     * Called after archiving is complete — receives total size in bytes.
-     */
-    onSuccess?: (bytes: number) => void;
-}
-/**
- * Creates a {@link ArchiveFormat } archive from a specified directory.
- *
- * This function uses the `archiver` library to package a directory into an archive file.
- * It supports optional compression for `zip` and returns a Promise that resolves
- * when the archive is successfully created.
- *
- * @example
- *
- * Function usage:
- *
- * ```ts
- * await createArchive({
- *   format: "zip",
- *   source: "dist/",
- *   destination: "dist.zip",
- * });
- * ```
- *
- *  CLI usage:
- * ```sh
- * npx js-utils-kit createArchive -f zip -s dist -d dist.zip
- * ```
- *
- * @param options - Archive creation options
- * @returns A Promise that resolves when the archive is created
- * @throws If an error occurs during the archiving process
- */
-declare function createArchive({ format, source, destination, options, log, onSuccess, }: CreateArchiveOptions): Promise<void>;
-
-declare const _default: {
-    createArchive: typeof createArchive;
-};
-
-export { createArchive, _default as default };
-export type { ArchiveFormat, CreateArchiveOptions };

package/dist/file/index.js

@@ -1 +0,0 @@
-import r from"fs";import o from"path";import e from"archiver";function t({format:t,source:i,destination:n,options:c={},log:s=!0,onSuccess:a}){const l=o.resolve(i);if(!r.existsSync(l)||!r.statSync(l).isDirectory())throw new Error(`Source directory "${i}" does not exist or is not a directory.`);const f=r.createWriteStream(n);"zip"===t&&(c={...c,zlib:{level:9}});const p=e(t,c);return new Promise((r,o)=>{f.on("close",()=>{const o=p.pointer();s&&console.log(`${n} created: ${o} total bytes`),a&&a(o),r()}),p.on("error",r=>{o(r)}),p.pipe(f),p.directory(i,!1),p.finalize().catch(r=>o(r instanceof Error?r:new Error(String(r))))})}var i={createArchive:t};export{t as createArchive,i as default};

package/dist/index.d.ts

@@ -1,37 +0,0 @@
-export { default as array, isArray } from './array/index.js';
-export { all, default as char, digits, lowercase, uppercase } from './char/index.js';
-export { Environment, default as env, getRunTimeEnvironment, isBrowser, isDev, isNode, isProd, isTest } from './env/index.js';
-export { ArchiveFormat, CreateArchiveOptions, createArchive, default as file } from './file/index.js';
-export { Hour, MinuteOrSecond, clamp, getMilliseconds, isEven, isOdd, default as number, randomFloat, randomInt } from './number/index.js';
-export { isEmptyObject, isNonEmptyObject, isObject, mergeObj, default as object } from './object/index.js';
-export { Trim, capitalize, containsWhitespace, countChars, countFrequencies, countLines, countSubstring, countWords, endsWithPunctuation, isAlphabetic, isCamelCase, isEmail, isKebabCase, isLowerCase, isNonEmptyString, isNumericString, isPascalCase, isSnakeCase, isString, isURL, isUpperCase, longestWord, longestWordLength, padLeft, padRight, repeatString, shortestWord, shortestWordLength, splitString, startsWithUppercase, default as string, stripSymbols, trim, truncate, uniqueChars } from './string/index.js';
-export { ArchiverOptions } from 'archiver';
-
-/**
- * Checks if a value is neither null nor undefined.
- * @param value - The value to check.
- * @returns True if the value is defined (not null or undefined), false otherwise.
- * @example
- * ```ts
- * isDefined(42); // true
- * isDefined("hello"); // true
- * isDefined(null); // false
- * isDefined(undefined); // false
- * ```
- */
-declare function isDefined<T>(value: T): boolean;
-/**
- * Checks if a value is either null or undefined.
- * @param value - The value to check.
- * @returns True if the value is null or undefined, false otherwise.
- * @example
- * ```ts
- * isUndefinedOrNull(null); // true
- * isUndefinedOrNull(undefined); // true
- * isUndefinedOrNull(0); // false
- * isUndefinedOrNull(""); // false
- * ```
- */
-declare function isUndefinedOrNull<T>(value: T): boolean;
-
-export { isDefined, isUndefinedOrNull };

package/dist/index.js

@@ -1 +0,0 @@
-export{default as array}from"./array/index.js";export{all,default as char,digits,lowercase,uppercase}from"./char/index.js";export{Environment,default as env,getRunTimeEnvironment,isBrowser,isDev,isNode,isProd,isTest}from"./env/index.js";export{createArchive,default as file}from"./file/index.js";export{clamp,getMilliseconds,isEven,isOdd,default as number,randomFloat,randomInt}from"./number/index.js";export{isEmptyObject,isNonEmptyObject,isObject,mergeObj,default as object}from"./object/index.js";export{capitalize,containsWhitespace,countChars,countFrequencies,countLines,countSubstring,countWords,endsWithPunctuation,isAlphabetic,isCamelCase,isEmail,isKebabCase,isLowerCase,isNonEmptyString,isNumericString,isPascalCase,isSnakeCase,isString,isURL,isUpperCase,longestWord,longestWordLength,padLeft,padRight,repeatString,shortestWord,shortestWordLength,splitString,startsWithUppercase,default as string,stripSymbols,trim,truncate,uniqueChars}from"./string/index.js";export{i as isArray,a as isDefined,b as isUndefinedOrNull}from"./validate-D9J7otjc.js";import"fs";import"path";import"archiver";

package/dist/number/index.cjs

@@ -1 +0,0 @@
-"use strict";function t(t,e,n){return Math.min(Math.max(t,e),n)}function e(t){return t%2==0}function n(t){return t%2!=0}function r(t,e){return Math.floor(Math.random()*(e-t+1))+t}function o(t,e){return Math.random()*(e-t)+t}function s(t=0,e=0,n=0,r=0){if([t,e,n,r].some(t=>t<0))throw new Error("All time values must be non-negative numbers.");return 1e3*(24*t*60*60+60*e*60+60*n+r)}Object.defineProperty(exports,"__esModule",{value:!0});var a={clamp:t,isEven:e,isOdd:n,randomInt:r,randomFloat:o,getMilliseconds:s};exports.clamp=t,exports.default=a,exports.getMilliseconds=s,exports.isEven=e,exports.isOdd=n,exports.randomFloat=o,exports.randomInt=r;

package/dist/number/index.d.ts

@@ -1,116 +0,0 @@
-/**
- * Clamps a number between a minimum and maximum value.
- *
- * Ensures that the returned number is not less than `min` and not more than `max`.
- *
- * @param value - The number to clamp.
- * @param min - The minimum allowed value.
- * @param max - The maximum allowed value.
- * @returns The clamped number.
- *
- * @example
- * clamp(5, 1, 10); // 5
- * clamp(0, 1, 10); // 1
- * clamp(15, 1, 10); // 10
- */
-declare function clamp(value: number, min: number, max: number): number;
-
-/**
- * Checks if a number is even.
- *
- * @param value - The number to check.
- * @returns True if the number is even, false otherwise.
- *
- * @example
- * isEven(4); // true
- * isEven(3); // false
- */
-declare function isEven(value: number): boolean;
-/**
- * Checks if a number is odd.
- *
- * @param value - The number to check.
- * @returns True if the number is odd, false otherwise.
- *
- * @example
- * isOdd(3); // true
- * isOdd(4); // false
- */
-declare function isOdd(value: number): boolean;
-
-/**
- * Returns a random integer between `min` and `max`, inclusive.
- *
- * @param min - Minimum value (inclusive).
- * @param max - Maximum value (inclusive).
- * @returns A random integer between min and max.
- *
- * @example
- * randomInt(1, 5); // 3
- * randomInt(10, 20); // 17
- */
-declare function randomInt(min: number, max: number): number;
-/**
- * Returns a random floating-point number between `min` and `max`.
- *
- * @param min - Minimum value (inclusive).
- * @param max - Maximum value (exclusive).
- * @returns A random float between min and max.
- *
- * @example
- * randomFloat(0, 1); // 0.624...
- * randomFloat(1.5, 5.2); // 3.1415...
- */
-declare function randomFloat(min: number, max: number): number;
-
-/**
- * Represents an hour value in a 24-hour format.
- *
- * @remarks
- * - Valid range is `0–23`.
- * - Used in {@link getMilliseconds}.
- */
-type Hour = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23;
-/**
- * Represents a minute or second value in time.
- *
- * @remarks
- * - Valid range is `0–59`.
- * - Used in {@link getMilliseconds}.
- */
-type MinuteOrSecond = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59;
-/**
- * Converts a time duration (days, hours, minutes, seconds) into total milliseconds.
- *
- * @returns The equivalent duration in milliseconds.
- *
- * @throws Will throw an error if any parameter is negative.
- *
- * @example
- * ```ts
- * getMilliseconds(1);             // 86400000 (1 day)
- * getMilliseconds(0, 1);          // 3600000  (1 hour)
- * getMilliseconds(0, 0, 30, 15);  // 1815000  (30 minutes 15 seconds)
- * ```
- */
-declare function getMilliseconds(
-/** Number of days. */
-days?: number, 
-/** Hour of the day (`0–23`). */
-hours?: Hour, 
-/** Minute value (`0–59`). */
-minutes?: MinuteOrSecond, 
-/** Second value (`0–59`). */
-seconds?: MinuteOrSecond): number;
-
-declare const _default: {
-    clamp: typeof clamp;
-    isEven: typeof isEven;
-    isOdd: typeof isOdd;
-    randomInt: typeof randomInt;
-    randomFloat: typeof randomFloat;
-    getMilliseconds: typeof getMilliseconds;
-};
-
-export { clamp, _default as default, getMilliseconds, isEven, isOdd, randomFloat, randomInt };
-export type { Hour, MinuteOrSecond };

package/dist/number/index.js

@@ -1 +0,0 @@
-function n(n,t,r){return Math.min(Math.max(n,t),r)}function t(n){return n%2==0}function r(n){return n%2!=0}function e(n,t){return Math.floor(Math.random()*(t-n+1))+n}function o(n,t){return Math.random()*(t-n)+n}function a(n=0,t=0,r=0,e=0){if([n,t,r,e].some(n=>n<0))throw new Error("All time values must be non-negative numbers.");return 1e3*(24*n*60*60+60*t*60+60*r+e)}var u={clamp:n,isEven:t,isOdd:r,randomInt:e,randomFloat:o,getMilliseconds:a};export{n as clamp,u as default,a as getMilliseconds,t as isEven,r as isOdd,o as randomFloat,e as randomInt};

package/dist/object/index.cjs

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("../validate-BKQ-HFTd.js");function t(e=!1,...r){const o=e=>"object"==typeof e&&null!==e,s={};for(const c of r)if(o(c))for(const r of Object.keys(c)){const n=c[r],y=s[r];Array.isArray(n)?s[r]=e&&Array.isArray(y)?[...y,...n]:[...n]:o(n)&&!Array.isArray(n)?s[r]=o(y)&&!Array.isArray(y)?t(e,y,n):t(e,{},n):s[r]=n}return s}function r(t){return e.isDefined(t)&&"object"==typeof t&&!e.isArray(t)&&Object.getPrototypeOf(t)===Object.prototype}function o(t){return null!==t&&"object"==typeof t&&0===Object.keys(t).length&&!e.isArray(t)}function s(t){return null!==t&&"object"==typeof t&&Object.keys(t).length>0&&!e.isArray(t)}var c={mergeObj:t,isObject:r,isEmptyObject:o,isNonEmptyObject:s};exports.default=c,exports.isEmptyObject=o,exports.isNonEmptyObject=s,exports.isObject=r,exports.mergeObj=t;

package/dist/object/index.d.ts

@@ -1,89 +0,0 @@
-/**
- * Deeply merges multiple source objects into one.
- *
- * - Object properties are merged recursively.
- * - If a key exists in multiple objects:
- *   - If the value is a plain object, it is deeply merged.
- *   - If the value is an array:
- *     - If `appendArray` is `true`, arrays are concatenated.
- *     - If `appendArray` is `false` (default), later arrays replace earlier ones.
- *   - Primitive values (string, number, boolean, etc.) are overwritten by later sources.
- *
- * - Objects passed later in the list of sources have **higher priority**.
- *   For example, values in the last object will override previous ones.
- * - If you want to give **priority to a specific object**, **pass it last**.
- *
- * @example
- * ```ts
- * const defaultConfig = { env: "dev", features: ["a"], flags: { debug: true } };
- * const userConfig = { env: "prod", features: ["b"], flags: { beta: true } };
- *
- * const result = mergeObj(defaultConfig, userConfig);
- * // {
- * //   env: "prod",
- * //   features: ["b"],        // replaced, not merged
- * //   flags: { debug: true, beta: true }
- * // }
- *
- * const result2 = mergeObj(true, defaultConfig, userConfig);
- * // {
- * //   env: "prod",
- * //   features: ["a", "b"],   // arrays merged
- * //   flags: { debug: true, beta: true }
- * // }
- * ```
- *
- * @param appendArray - If `true`, arrays are concatenated. If `false` (default), arrays are replaced.
- * @param sources - One or more objects to deeply merge.
- * @returns A new object containing deeply merged keys and values.
- */
-declare function mergeObj(appendArray?: boolean, ...sources: object[]): object;
-
-/**
- * Checks if a value is a plain object (created by {} or new Object()).
- * @param value - The value to check.
- * @returns True if the value is a plain object, false otherwise.
- * @example
- * ```ts
- * isObject({}); // true
- * isObject(new Object()); // true
- * isObject([]); // false
- * isObject(new Date()); // false
- * ```
- */
-declare function isObject<T>(value: T): boolean;
-/**
- * Checks if a value is an empty object (has no enumerable own properties).
- * @param value - The value to check.
- * @returns True if the value is a non-null object with no enumerable own properties, false otherwise.
- * @example
- * ```ts
- * isEmptyObject({}); // true
- * isEmptyObject({ key: 'value' }); // false
- * isEmptyObject(null); // false
- * isEmptyObject([]); // false
- * ```
- */
-declare function isEmptyObject(value: object): boolean;
-/**
- * Checks if a value is a non-empty object (has at least one enumerable own property).
- * @param value - The value to check.
- * @returns True if the value is a non-null object with at least one enumerable own property, false otherwise.
- * @example
- * ```ts
- * isNonEmptyObject({ key: 'value' }); // true
- * isNonEmptyObject({}); // false
- * isNonEmptyObject(null); // false
- * isNonEmptyObject([]); // false
- * ```
- */
-declare function isNonEmptyObject(value: object): boolean;
-
-declare const _default: {
-    mergeObj: typeof mergeObj;
-    isObject: typeof isObject;
-    isEmptyObject: typeof isEmptyObject;
-    isNonEmptyObject: typeof isNonEmptyObject;
-};
-
-export { _default as default, isEmptyObject, isNonEmptyObject, isObject, mergeObj };

package/dist/object/index.js

@@ -1 +0,0 @@
-import{i as t,a as e}from"../validate-D9J7otjc.js";function r(t=!1,...e){const o=t=>"object"==typeof t&&null!==t,n={};for(const c of e)if(o(c))for(const e of Object.keys(c)){const y=c[e],s=n[e];Array.isArray(y)?n[e]=t&&Array.isArray(s)?[...s,...y]:[...y]:o(y)&&!Array.isArray(y)?n[e]=o(s)&&!Array.isArray(s)?r(t,s,y):r(t,{},y):n[e]=y}return n}function o(r){return e(r)&&"object"==typeof r&&!t(r)&&Object.getPrototypeOf(r)===Object.prototype}function n(e){return null!==e&&"object"==typeof e&&0===Object.keys(e).length&&!t(e)}function c(e){return null!==e&&"object"==typeof e&&Object.keys(e).length>0&&!t(e)}var y={mergeObj:r,isObject:o,isEmptyObject:n,isNonEmptyObject:c};export{y as default,n as isEmptyObject,c as isNonEmptyObject,o as isObject,r as mergeObj};

package/dist/string/index.cjs

@@ -1 +0,0 @@
-"use strict";function t(t){return t.replace(/^\w/,t=>t.toUpperCase())}function e(t,e,n=" "){return t.padStart(e,n)}function n(t,e,n=" "){return t.padEnd(e,n)}function r(t,e,n="..."){return e<=0?"":t.length<=e?t:n.length>=e?n.slice(0,e):t.trim().slice(0,e)+n}function s(t,e){return t.repeat(e)}function i(t,e=""){return t.replace(/[^\p{L}\p{N}\s]/gu,e)}function o(t,e=/\s+/){return t.split(e)}function u(t,e){return e?[...t].filter(t=>t===e).length:o(t).length}function a(t){return o(t.trim()).length}function p(t,e){return 0===e.length?0:o(t,e).length-1}function c(t){return[...t].reduce((t,e)=>(t[e]=(t[e]||0)+1,t),{})}function l(t){return t?o(t,/\r\n|\r|\n/).length:0}function h(t){return[...new Set(t)]}function g(t){const e=o(t).map(t=>i(t)).filter(Boolean);return 0===e.length?0:e.reduce((t,e)=>Math.max(t,e.length),0)}function f(t){const e=o(t.trim()).map(t=>i(t)).filter(Boolean);return 0===e.length?0:e.reduce((t,e)=>Math.min(t,e.length),1/0)}function x(t){const e=o(t.trim()).map(t=>i(t)).filter(Boolean);if(0===e.length)return"";const n=Math.max(...e.map(t=>t.length)),r=e.filter(t=>t.length===n),s=[...new Set(r)];return 1===s.length?s[0]:s}function m(t){const e=o(t.trim()).map(t=>i(t)).filter(Boolean);if(0===e.length)return"";const n=Math.min(...e.map(t=>t.length)),r=e.filter(t=>t.length===n),s=[...new Set(r)];return 1===s.length?s[0]:s}Object.defineProperty(exports,"__esModule",{value:!0});const d={function:t=>t.trim(),start:t=>t.trimStart(),end:t=>t.trimEnd(),normalizeWhitespace:t=>t.trim().replace(/\s+/g," ")};function S(t){return null!=t&&"string"==typeof t}function C(t,e=!0){return!!S(t)&&("string"==typeof t&&(e?t.trim().length>0:t.length>0))}function z(t){try{return new URL(t),!0}catch{return!1}}function W(t){if("string"!=typeof t)throw new TypeError("Expected a string");if(t.length>254)return!1;const e=t.split("@");if(2!==e.length)return!1;const[n,r]=e;if(0===n.length||n.length>64)return!1;if(0===r.length||r.length>255)return!1;return!!/^[a-zA-Z0-9_%+-]+(\.[a-zA-Z0-9_%+-]+)*$/.test(n)&&!!/^(?!.*\.\.)(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63}(?<!-))*\.[A-Za-z]{2,}$/.test(r)}function L(t){return/^[a-zA-Z]+$/.test(t)}function A(t){return!isNaN(Number(t))&&!isNaN(parseFloat(t))}function b(t){return/^[A-Z]/.test(t)}function Z(t){return/[\p{P}]$/u.test(t)}function y(t){return/\s/.test(t)}function N(t){return/^[a-z][a-zA-Z0-9]*$/.test(t)}function $(t){return/^[A-Z][a-zA-Z0-9]*$/.test(t)}function w(t){return/^[a-z0-9]+(-[a-z0-9]+)*$/.test(t)}function E(t){return/^[a-z0-9]+(_[a-z0-9]+)*$/.test(t)}function U(t){return/^[A-Z]+$/.test(t)}function P(t){return/^[a-z]+$/.test(t)}var M={capitalize:t,splitString:o,countChars:u,countWords:a,countSubstring:p,countFrequencies:c,countLines:l,uniqueChars:h,longestWordLength:g,shortestWordLength:f,longestWord:x,shortestWord:m,padLeft:e,padRight:n,truncate:r,repeatString:s,stripSymbols:i,trim:d,isString:S,isNonEmptyString:C,isURL:z,isEmail:W,isAlphabetic:L,isNumericString:A,startsWithUppercase:b,endsWithPunctuation:Z,containsWhitespace:y,isCamelCase:N,isPascalCase:$,isKebabCase:w,isSnakeCase:E,isUpperCase:U,isLowerCase:P};exports.capitalize=t,exports.containsWhitespace=y,exports.countChars=u,exports.countFrequencies=c,exports.countLines=l,exports.countSubstring=p,exports.countWords=a,exports.default=M,exports.endsWithPunctuation=Z,exports.isAlphabetic=L,exports.isCamelCase=N,exports.isEmail=W,exports.isKebabCase=w,exports.isLowerCase=P,exports.isNonEmptyString=C,exports.isNumericString=A,exports.isPascalCase=$,exports.isSnakeCase=E,exports.isString=S,exports.isURL=z,exports.isUpperCase=U,exports.longestWord=x,exports.longestWordLength=g,exports.padLeft=e,exports.padRight=n,exports.repeatString=s,exports.shortestWord=m,exports.shortestWordLength=f,exports.splitString=o,exports.startsWithUppercase=b,exports.stripSymbols=i,exports.trim=d,exports.truncate=r,exports.uniqueChars=h;