js-utils-kit 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var e=require("./char/index.cjs"),r=require("./env/index.cjs"),i=require("./file/index.cjs"),u=require("./number/index.cjs"),s=require("./object/index.cjs"),t=require("./string/index.cjs");require("fs"),require("path"),require("constants"),require("stream"),require("util"),require("assert"),require("buffer"),require("node:url"),require("node:path"),require("node:fs"),require("node:fs/promises"),require("node:events"),require("node:stream"),require("node:string_decoder"),require("zlib"),exports.char=e.default,exports.env=r.default,exports.file=i.default,exports.number=u.default,exports.object=s.default,exports.string=t.default;

package/dist/index.d.ts

@@ -1,71 +1,7 @@
-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>;
-
-export { createArchive };
-export type { ArchiveFormat, CreateArchiveOptions };
+export { default as char } from './char/index.js';
+export { default as env } from './env/index.js';
+export { default as file } from './file/index.js';
+export { default as number } from './number/index.js';
+export { default as object } from './object/index.js';
+export { default as string } from './string/index.js';
+import 'archiver';

package/dist/index.js

@@ -0,0 +1 @@
+export{default as char}from"./char/index.js";export{default as env}from"./env/index.js";export{default as file}from"./file/index.js";export{default as number}from"./number/index.js";export{default as object}from"./object/index.js";export{default as string}from"./string/index.js";import"fs";import"path";import"constants";import"stream";import"util";import"assert";import"buffer";import"node:url";import"node:path";import"node:fs";import"node:fs/promises";import"node:events";import"node:stream";import"node:string_decoder";import"zlib";

package/dist/number/index.cjs

@@ -0,0 +1 @@
+"use strict";function t(t,r,n){return Math.min(Math.max(t,r),n)}function r(t){return t%2==0}function n(t){return t%2!=0}function o(t,r){return Math.floor(Math.random()*(r-t+1))+t}function e(t,r){return Math.random()*(r-t)+t}Object.defineProperty(exports,"__esModule",{value:!0});var a={clamp:t,isEven:r,isOdd:n,randomInt:o,randomFloat:e};exports.clamp=t,exports.default=a,exports.isEven=r,exports.isOdd=n,exports.randomFloat=e,exports.randomInt=o;

package/dist/number/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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;
+
+declare const _default: {
+    clamp: typeof clamp;
+    isEven: typeof isEven;
+    isOdd: typeof isOdd;
+    randomInt: typeof randomInt;
+    randomFloat: typeof randomFloat;
+};
+
+export { clamp, _default as default, isEven, isOdd, randomFloat, randomInt };

package/dist/number/index.js

@@ -0,0 +1 @@
+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 a(n,t){return Math.floor(Math.random()*(t-n+1))+n}function o(n,t){return Math.random()*(t-n)+n}var u={clamp:n,isEven:t,isOdd:r,randomInt:a,randomFloat:o};export{n as clamp,u as default,t as isEven,r as isOdd,o as randomFloat,a as randomInt};

package/dist/object/index.cjs

@@ -0,0 +1 @@
+"use strict";function r(e=!1,...t){const o=r=>"object"==typeof r&&null!==r&&!Array.isArray(r);return t.reduce((t,s)=>{for(const n in s){const a=s[n],u=t[n];Array.isArray(a)?t[n]=e&&Array.isArray(u)?[...u,...a]:[...a]:o(a)?t[n]=r(e,o(u)?u:{},a):t[n]=a}return t},{})}Object.defineProperty(exports,"__esModule",{value:!0});var e={mergeObj:r};exports.default=e,exports.mergeObj=r;

package/dist/object/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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(false, 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: Record<string, unknown>[]): Record<string, unknown>;
+
+declare const _default: {
+    mergeObj: typeof mergeObj;
+};
+
+export { _default as default, mergeObj };

package/dist/object/index.js

@@ -0,0 +1 @@
+function r(e=!1,...t){const a=r=>"object"==typeof r&&null!==r&&!Array.isArray(r);return t.reduce((t,n)=>{for(const o in n){const s=n[o],y=t[o];Array.isArray(s)?t[o]=e&&Array.isArray(y)?[...y,...s]:[...s]:a(s)?t[o]=r(e,a(y)?y:{},s):t[o]=s}return t},{})}var e={mergeObj:r};export{e as default,r as mergeObj};

package/dist/string/index.cjs

@@ -0,0 +1 @@
+"use strict";function t(t){return null!=t&&"string"==typeof t}function r(r,e=!0){return!!t(r)&&(e?r.trim().length>0:r.length>0)}function e(t){try{return new URL(t),!0}catch{return!1}}function i(t){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)}function n(t){return/^[a-zA-Z]+$/.test(t)}function s(t){return!isNaN(Number(t))&&!isNaN(parseFloat(t))}Object.defineProperty(exports,"__esModule",{value:!0});var u={isString:t,isNonEmptyString:r,isURL:e,isEmail:i,isAlphabetic:n,isNumericString:s};exports.default=u,exports.isAlphabetic=n,exports.isEmail=i,exports.isNonEmptyString=r,exports.isNumericString=s,exports.isString=t,exports.isURL=e;

package/dist/string/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Determines whether the provided value is a string.
+ *
+ * This function returns `true` if the input is a non-null, non-undefined
+ * primitive string. It acts as a type guard, so TypeScript will narrow
+ * the type to `string` when used in conditionals.
+ *
+ * @template T - The type of the input value.
+ * @param value - The value to be checked.
+ * @returns - Whether the value is a string (`true`) or not (`false`).
+ *
+ * @example
+ * ```ts
+ * isString("hello"); // true
+ * isString(123);     // false
+ * isString(null);    // false
+ * isString(undefined); // false
+ *
+ * const value: unknown = "test";
+ * if (isString(value)) {
+ *   console.log(value.toUpperCase());
+ * }
+ * ```
+ */
+declare function isString<T>(value: T): value is T & string;
+/**
+ * Determines whether the given value is a non-empty string.
+ *
+ * This function first checks if the input is a string using {@link isString}.
+ * If it is not a string, the function returns `false`.
+ * If it is a string, it then checks whether the string contains any non-empty content.
+ *
+ * By default, the function trims the string before checking its length,
+ * which means strings containing only whitespace (e.g., `"   "`) will be considered empty.
+ * This behavior can be controlled using the `trim` parameter.
+ *
+ * @template T - The type of the value being checked.
+ *
+ * @param value - The value to validate as a non-empty string.
+ * @param trim - Whether to trim whitespace from the string before checking its length.
+ *               Defaults to `true`.
+ *
+ * @returns - A boolean indicating whether the input is a non-empty string.
+ *
+ * @example
+ * isNonEmptyString('hello'); // true
+ * isNonEmptyString('   '); // false (trim is true by default)
+ * isNonEmptyString('   ', false); // true (whitespace is counted)
+ * isNonEmptyString(123); // false
+ * isNonEmptyString(null); // false
+ */
+declare function isNonEmptyString<T>(value: T, trim?: boolean): boolean;
+/**
+ * Checks whether a given string is a valid absolute URL.
+ *
+ * This function uses the native `URL` constructor to determine if the input is a valid,
+ * absolute URL with a supported protocol (e.g., `http`, `https`, `ftp`, etc.).
+ *
+ * @param value - The string to validate as a URL.
+ * @returns - `true` if the string is a valid absolute URL; otherwise, `false`.
+ *
+ * @example
+ * isURL('https://example.com'); // true
+ * isURL('ftp://files.example.com'); // true
+ * isURL('invalid-url'); // false
+ * isURL('/relative/path'); // false
+ */
+declare function isURL(value: string): boolean;
+/**
+ * Checks whether a given string is a valid email address.
+ *
+ * This function uses a practical regular expression to validate email addresses,
+ * allowing most common formats while ignoring edge cases defined by full RFC 5322.
+ * It requires the presence of an `@` symbol and at least one `.` after it.
+ *
+ * @param value - The string to validate as an email address.
+ * @returns - `true` if the string is a valid email; otherwise, `false`.
+ *
+ * @example
+ * isEmail('user@example.com'); // true
+ * isEmail('first.last@college.university.in'); // true
+ * isEmail('invalid-email'); // false
+ * isEmail('name@domain'); // false
+ */
+declare function isEmail(value: string): boolean;
+/**
+ * Checks if a string contains only alphabetic characters (A–Z, a–z).
+ *
+ * @param value - The string to check.
+ * @returns - `true` if the string contains only letters; otherwise, `false`.
+ *
+ * @example
+ * isAlphabetic("Hello"); // true
+ * isAlphabetic("world123"); // false
+ * isAlphabetic("Test!"); // false
+ */
+declare function isAlphabetic(value: string): boolean;
+/**
+ * Checks whether a given string represents a valid numeric value.
+ *
+ * This function attempts to convert the input string to a number using
+ * both `Number()` and `parseFloat()`. It returns `true` only if both
+ * conversions do not result in `NaN`, ensuring that the input is
+ * a fully numeric string.
+ *
+ * Accepts integers, decimals, scientific notation (e.g. "1e5"), and
+ * ignores surrounding whitespace. Does not allow trailing or embedded characters
+ * like "123abc" or "abc123".
+ *
+ * @param value - The string to validate.
+ * @returns - `true` if the string represents a valid number; otherwise, `false`.
+ *
+ * @example
+ * isNumericString("42"); // true
+ * isNumericString("-3.14"); // true
+ * isNumericString("1e5"); // true
+ * isNumericString("  123 "); // true
+ * isNumericString("123abc"); // false
+ * isNumericString("abc123"); // false
+ *
+ * See also:
+ * - {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number Number()}
+ * - {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat parseFloat()}
+ * - {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN isNaN()}
+ */
+declare function isNumericString(value: string): boolean;
+
+declare const _default: {
+    isString: typeof isString;
+    isNonEmptyString: typeof isNonEmptyString;
+    isURL: typeof isURL;
+    isEmail: typeof isEmail;
+    isAlphabetic: typeof isAlphabetic;
+    isNumericString: typeof isNumericString;
+};
+
+export { _default as default, isAlphabetic, isEmail, isNonEmptyString, isNumericString, isString, isURL };

package/dist/string/index.js

@@ -0,0 +1 @@
+function t(t){return null!=t&&"string"==typeof t}function n(n,r=!0){return!!t(n)&&(r?n.trim().length>0:n.length>0)}function r(t){try{return new URL(t),!0}catch{return!1}}function i(t){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)}function e(t){return/^[a-zA-Z]+$/.test(t)}function u(t){return!isNaN(Number(t))&&!isNaN(parseFloat(t))}var s={isString:t,isNonEmptyString:n,isURL:r,isEmail:i,isAlphabetic:e,isNumericString:u};export{s as default,e as isAlphabetic,i as isEmail,n as isNonEmptyString,u as isNumericString,t as isString,r as isURL};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "js-utils-kit",
   "displayName": "JS Utils Kit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Essential JavaScript helpers",
   "license": "MIT",
   "private": false,
@@ -19,7 +19,22 @@
     "utils",
     "helpers",
     "toolkit",
-    "typescript"
+    "typescript",
+    "js",
+    "utility",
+    "functions",
+    "modules",
+    "typed",
+    "common",
+    "cli",
+    "merge",
+    "random",
+    "string",
+    "array",
+    "object",
+    "number",
+    "date",
+    "type-check"
   ],
   "type": "module",
   "files": [
@@ -28,19 +43,49 @@
   "bin": {
     "js-utils-kit": "dist/cli/index.js"
   },
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.esm.js",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.esm.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.cjs.js"
-      }
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./char": {
+      "import": "./dist/char/index.js",
+      "require": "./dist/char/index.cjs",
+      "types": "./dist/char/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli/index.js",
+      "require": "./dist/cli/index.cjs",
+      "types": "./dist/cli/index.d.ts"
+    },
+    "./env": {
+      "import": "./dist/env/index.js",
+      "require": "./dist/env/index.cjs",
+      "types": "./dist/env/index.d.ts"
+    },
+    "./file": {
+      "import": "./dist/file/index.js",
+      "require": "./dist/file/index.cjs",
+      "types": "./dist/file/index.d.ts"
+    },
+    "./number": {
+      "import": "./dist/number/index.js",
+      "require": "./dist/number/index.cjs",
+      "types": "./dist/number/index.d.ts"
+    },
+    "./object": {
+      "import": "./dist/object/index.js",
+      "require": "./dist/object/index.cjs",
+      "types": "./dist/object/index.d.ts"
+    },
+    "./string": {
+      "import": "./dist/string/index.js",
+      "require": "./dist/string/index.cjs",
+      "types": "./dist/string/index.d.ts"
     }
   },
   "lint-staged": {
@@ -48,7 +93,9 @@
   },
   "scripts": {
     "test": "jest",
-    "build": "rollup -c && yarn docs",
+    "prebuild": "yarn gen:indexes",
+    "build": "rollup -c",
+    "postbuild": "yarn gen:exports && yarn docs",
     "release": "release-it",
     "watch": "rollup -c --watch",
     "lint": "eslint .",
@@ -56,7 +103,10 @@
     "format": "prettier --write",
     "format:check": "prettier --check .",
     "prepare": "husky",
-    "docs": "typedoc"
+    "prepare:release": "yarn test && yarn prebuild && yarn build && yarn postbuild",
+    "docs": "typedoc",
+    "gen:exports": "node scripts/gen-exports.js",
+    "gen:indexes": "node scripts/gen-indexes.js"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",
@@ -71,14 +121,12 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.4",
     "archiver": "^7.0.1",
-    "commander": "^14.0.0",
     "eslint": "^9.29.0",
     "globals": "^16.2.0",
     "husky": "^9.1.7",
     "jest": "^30.0.3",
     "jest-environment-node": "^30.0.2",
     "lint-staged": "^16.1.2",
-    "ora": "^8.2.0",
     "prettier": "^3.6.0",
     "release-it": "^19.0.3",
     "rollup": "^4.44.0",
@@ -90,5 +138,9 @@
     "typedoc": "^0.28.5",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "ora": "^8.2.0"
   }
 }