js-utils-kit 0.0.0 → 0.2.0

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

@@ -0,0 +1,7 @@
+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,72 +1,110 @@
-{
-  "name": "js-utils-kit",
-  "version": "0.0.0",
-  "description": "Essential JavaScript helpers",
-  "license": "MIT",
-  "private": false,
-  "repository": "https://github.com/TenEplaysOfficial/js-utils-kit",
-  "author": {
-    "name": "Sriman",
-    "email": "136729116+TenEplaysOfficial@users.noreply.github.com",
-    "url": "https://tene.vercel.app"
-  },
-  "keywords": [
-    "javascript",
-    "utils",
-    "helpers",
-    "toolkit",
-    "typescript",
-    "promise",
-    "array",
-    "object",
-    "small"
-  ],
-  "type": "module",
-  "files": [
-    "dist/**/*"
-  ],
-  "bin": {
-    "js-utils-kit": "dist/index.js"
-  },
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.esm.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"
-      }
-    }
-  },
-  "scripts": {
-    "build": "rollup -c && yarn types",
-    "types": "tsc",
-    "watch": "rollup -c --watch",
-    "lint": "eslint .",
-    "format": "prettier --write ."
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.29.0",
-    "@eslint/json": "^0.12.0",
-    "@eslint/markdown": "^6.6.0",
-    "@rollup/plugin-commonjs": "^28.0.6",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.3",
-    "eslint": "^9.29.0",
-    "globals": "^16.2.0",
-    "prettier": "^3.6.0",
-    "rollup": "^4.44.0",
-    "rollup-plugin-delete": "^3.0.1",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "rollup-plugin-terser": "^7.0.2",
-    "tslib": "^2.8.1",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.35.0"
-  }
-}
+{
+  "name": "js-utils-kit",
+  "displayName": "JS Utils Kit",
+  "version": "0.2.0",
+  "description": "Essential JavaScript helpers",
+  "license": "MIT",
+  "private": false,
+  "repository": "https://github.com/TenEplaysOfficial/js-utils-kit",
+  "bugs": {
+    "url": "https://github.com/TenEplaysOfficial/js-utils-kit/issues"
+  },
+  "author": {
+    "name": "Sriman",
+    "email": "136729116+TenEplaysOfficial@users.noreply.github.com",
+    "url": "https://tene.vercel.app"
+  },
+  "keywords": [
+    "javascript",
+    "utils",
+    "helpers",
+    "toolkit",
+    "typescript",
+    "js",
+    "utility",
+    "functions",
+    "modules",
+    "typed",
+    "common",
+    "cli",
+    "merge",
+    "random",
+    "string",
+    "array",
+    "object",
+    "number",
+    "date",
+    "type-check"
+  ],
+  "type": "module",
+  "files": [
+    "dist/**/*"
+  ],
+  "bin": {
+    "js-utils-kit": "dist/cli/index.js"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "lint-staged": {
+    "*.{js,mjs,ts,json,md,yml}": "yarn format"
+  },
+  "scripts": {
+    "test": "jest",
+    "prebuild": "yarn gen:indexes",
+    "build": "rollup -c",
+    "postbuild": "yarn docs",
+    "release": "release-it",
+    "watch": "rollup -c --watch",
+    "lint": "eslint .",
+    "lint:fix": "npx eslint . --fix",
+    "format": "prettier --write",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "docs": "typedoc",
+    "gen:exports": "node scripts/gen-exports.js",
+    "gen:indexes": "node scripts/gen-indexes.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@eslint/json": "^0.12.0",
+    "@eslint/markdown": "^6.6.0",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.3",
+    "@types/archiver": "^6.0.3",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.4",
+    "archiver": "^7.0.1",
+    "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",
+    "prettier": "^3.6.0",
+    "release-it": "^19.0.3",
+    "rollup": "^4.44.0",
+    "rollup-plugin-delete": "^3.0.1",
+    "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "ts-jest": "^29.4.0",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "ora": "^8.2.0"
+  }
+}