{"_id":"@cabdi_waaxid/utils","name":"@cabdi_waaxid/utils","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cabdi_waaxid/utils","version":"1.0.0","description":"A collection of reusable JavaScript utility functions with multi-option modes","main":"index.js","type":"module","keywords":["javascript","utils","utility","helpers","array","string","object","math","date"],"author":{"name":"Cabdi Waaxid Siciid"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cabdiwaaxid-so/utils.git"},"engines":{"node":">=14"},"_id":"@cabdi_waaxid/utils@1.0.0","gitHead":"b248b594b84a54cb6bb8bda426cac2ba5fb773b6","bugs":{"url":"https://github.com/cabdiwaaxid-so/utils/issues"},"homepage":"https://github.com/cabdiwaaxid-so/utils#readme","_nodeVersion":"24.7.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-nDnvrdoiiG24ESk0ZqZeGbPqUUN+LqV9hCRZWJyn5C+kZnXTC6pnQGiYUzoYQhw41wLJdV2hznO5VHZ6NH+SzQ==","shasum":"d8574d07afec7e4012e7b8706eb041edd5ef2c4b","tarball":"https://registry.npmjs.org/@cabdi_waaxid/utils/-/utils-1.0.0.tgz","fileCount":12,"unpackedSize":25508,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDpek2AtiZg7So87OZdBnX9ng5bm5QayoCOO9dCry91mgIhAMwBEIMLbq3c1pTQz8m2X26kQMdq1IjT1/GVmUUbx0cc"}]},"_npmUser":{"name":"cabdi_waaxid","email":"cabdiwaaxidsiciid100@gmail.com"},"directories":{},"maintainers":[{"name":"cabdi_waaxid","email":"cabdiwaaxidsiciid100@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/utils_1.0.0_1759009444376_0.8040998430847348"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-27T21:44:04.276Z","1.0.0":"2025-09-27T21:44:04.602Z","modified":"2025-09-27T21:44:04.897Z"},"maintainers":[{"name":"cabdi_waaxid","email":"cabdiwaaxidsiciid100@gmail.com"}],"description":"A collection of reusable JavaScript utility functions with multi-option modes","homepage":"https://github.com/cabdiwaaxid-so/utils#readme","keywords":["javascript","utils","utility","helpers","array","string","object","math","date"],"repository":{"type":"git","url":"git+https://github.com/cabdiwaaxid-so/utils.git"},"author":{"name":"Cabdi Waaxid Siciid"},"bugs":{"url":"https://github.com/cabdiwaaxid-so/utils/issues"},"license":"MIT","readme":"# @cabdi_waaxid/utils\n\nA comprehensive collection of reusable JavaScript utility functions with multi-option modes. This library provides flexible, well-documented functions for string manipulation, array operations, object handling, mathematical calculations, and date formatting.\n\n## Features\n\n- 🎯 **Multi-mode functions** - Each function can return a specific result or all available formats\n- 📚 **Comprehensive JSDoc** - Full documentation with examples and type definitions\n- 🔧 **Tree-shakable** - Only import what you need\n- 🎪 **Flexible options** - Customize behavior with intuitive options objects\n- 💪 **Type-safe** - Written with JSDoc for better IDE support\n- 🚀 **Zero dependencies** - Lightweight and fast\n\n## Installation\n\n```bash\nnpm install @cabdi_waaxid/utils\n```\n\n## Quick Start\n\n```javascript\nimport { capitalize, arrayUtils, deepClone } from '@cabdi_waaxid/utils';\n\n// Simple usage with specific mode\nconst result = capitalize('hello world', { mode: 'firstUpper' });\nconsole.log(result); // 'Hello world'\n\n// Get all available formats\nconst formats = capitalize('hello world');\nconsole.log(formats.titleCase); // 'Hello World'\nconsole.log(formats.allUpper);  // 'HELLO WORLD'\n\n// Array operations\nconst shuffled = arrayUtils([1, 2, 3, 4], { mode: 'shuffle' });\nconsole.log(shuffled); // [3, 1, 4, 2] (random order)\n\n// Deep cloning\nconst original = { a: 1, b: { c: 2 } };\nconst cloned = deepClone(original, { mode: 'json' });\n```\n\n## API Reference\n\n### String Utilities\n\n#### `capitalize(str, options)`\n\nCapitalize strings with various formatting options.\n\n```javascript\nimport { capitalize } from '@cabdi_waaxid/utils';\n\n// Basic capitalization\ncapitalize('hello world', { mode: 'firstUpper' }); // 'Hello world'\n\n// Title case\ncapitalize('hello world', { mode: 'titleCase' }); // 'Hello World'\n\n// All uppercase\ncapitalize('hello world', { mode: 'allUpper' }); // 'HELLO WORLD'\n\n// Get all formats\nconst formats = capitalize('hello world');\nconsole.log(formats.firstUpper); // 'Hello world'\nconsole.log(formats.titleCase);  // 'Hello World'\nconsole.log(formats.allLower);   // 'hello world'\n```\n\n**Options:**\n- `mode`: 'firstUpper' | 'allUpper' | 'allLower' | 'titleCase' | 'upperByIndex' | 'lowerByIndex'\n- `index`: Index for character/word operations (default: 0)\n- `char`: Operate on characters (boolean)\n- `word`: Operate on words (boolean)\n- `every`: Apply to every occurrence (boolean)\n\n#### `truncate(str, options)`\n\nTruncate strings with various strategies.\n\n```javascript\nimport { truncate } from '@cabdi_waaxid/utils';\n\n// End truncation\ntruncate('This is a very long string', { \n  mode: 'end', \n  length: 10 \n}); // 'This is a...'\n\n// Middle truncation\ntruncate('This is a very long string', {\n  mode: 'middle',\n  length: 15\n}); // 'This is...string'\n\n// Smart truncation (at word boundary)\ntruncate('This is a very long string', {\n  mode: 'smart', \n  length: 12\n}); // 'This is a...'\n\n// Custom omission\ntruncate('Long text here', {\n  mode: 'end',\n  length: 8,\n  omission: ' […]'\n}); // 'Long tex […]'\n```\n\n**Options:**\n- `mode`: 'end' | 'start' | 'middle' | 'smart'\n- `length`: Maximum length (default: 50)\n- `omission`: Truncation indicator (default: '...')\n- `position\\**: Truncation position\n\n### Array Utilities\n\n#### `arrayUtils(arr, options)`\n\nPerform various array operations.\n\n```javascript\nimport { arrayUtils } from '@cabdi_waaxid/utils';\n\nconst numbers = [1, 2, 3, 4, 5];\n\n// Reverse array\narrayUtils(numbers, { mode: 'reverse' }); // [5, 4, 3, 2, 1]\n\n// Shuffle array\narrayUtils(numbers, { mode: 'shuffle' }); // [3, 1, 5, 2, 4] (random)\n\n// Get first element\narrayUtils(numbers, { mode: 'first' }); // 1\n\n// Get random element\narrayUtils(numbers, { mode: 'random' }); // 3 (random)\n\n// All operations at once\nconst formats = arrayUtils(numbers);\nconsole.log(formats.reverse); // [5, 4, 3, 2, 1]\nconsole.log(formats.shuffle); // [2, 5, 1, 4, 3]\nconsole.log(formats.first);   // 1\n```\n\n#### `unique(arr, options)`\n\nRemove duplicates from arrays.\n\n```javascript\nimport { unique } from '@cabdi_waaxid/utils';\n\nconst withDuplicates = [1, 2, 2, 3, 4, 4, 4, 1];\n\n// Simple deduplication\nunique(withDuplicates, { mode: 'simple' }); // [1, 2, 3, 4]\n\n// Sorted deduplication\nunique(withDuplicates, { mode: 'sorted' }); // [1, 2, 3, 4] (sorted)\n\nconst formats = unique(withDuplicates);\nconsole.log(formats.simple); // [1, 2, 3, 4]\nconsole.log(formats.sorted); // [1, 2, 3, 4]\n```\n\n#### `chunk(arr, options)`\n\nSplit arrays into chunks.\n\n```javascript\nimport { chunk } from '@cabdi_waaxid/utils';\n\nconst array = [1, 2, 3, 4, 5, 6, 7];\n\n// Fixed-size chunks\nchunk(array, { mode: 'fixed', size: 2 }); // [[1, 2], [3, 4], [5, 6], [7]]\n\n// Overlapping chunks\nchunk(array, { mode: 'overlapping', size: 3 }); \n// [[1, 2, 3], [2, 3, 4], [3, 4, 5], [4, 5, 6], [5, 6, 7]]\n\n// Fill incomplete chunks\nchunk(array, { mode: 'fill', size: 3, fillValue: 0 });\n// [[1, 2, 3], [4, 5, 6], [7, 0, 0]]\n```\n\n**Options:**\n- `mode`: 'fixed' | 'overlapping' | 'fill'\n- `size\\**: Chunk size (default: 2)\n- `fillValue\\**: Value to fill incomplete chunks\n\n### Object Utilities\n\n#### `deepClone(obj, options)`\n\nCreate deep clones of objects.\n\n```javascript\nimport { deepClone } from '@cabdi_waaxid/utils';\n\nconst original = { \n  a: 1, \n  b: { \n    c: 2,\n    d: [3, 4, 5]\n  } \n};\n\n// JSON-based clone\ndeepClone(original, { mode: 'json' });\n\n// Structured clone (if available)\ndeepClone(original, { mode: 'structured' });\n\n// Recursive clone\ndeepClone(original, { mode: 'recursive' });\n\n// Compare all methods\nconst formats = deepClone(original);\nconsole.log(formats.json);       // JSON method\nconsole.log(formats.structured); // structuredClone API\nconsole.log(formats.recursive);  // Custom recursive\n```\n\n#### `merge(target, source, options)`\n\nMerge objects with various strategies.\n\n```javascript\nimport { merge } from '@cabdi_waaxid/utils';\n\nconst obj1 = { a: 1, b: { c: 2 }, d: [1, 2] };\nconst obj2 = { b: { d: 3 }, e: 4, d: [3, 4] };\n\n// Shallow merge\nmerge(obj1, obj2, { mode: 'shallow' });\n// { a: 1, b: { d: 3 }, d: [3, 4], e: 4 }\n\n// Deep merge\nmerge(obj1, obj2, { mode: 'deep' });\n// { a: 1, b: { c: 2, d: 3 }, d: [3, 4], e: 4 }\n\n// Array concatenation\nmerge(obj1, obj2, { mode: 'concat' });\n// { a: 1, b: { d: 3 }, d: [1, 2, 3, 4], e: 4 }\n```\n\n### Math Utilities\n\n#### `random(options)`\n\nGenerate random values with various distributions.\n\n```javascript\nimport { random } from '@cabdi_waaxid/utils';\n\n// Random integer\nrandom({ mode: 'integer', min: 1, max: 100 }); // 42\n\n// Random float\nrandom({ mode: 'uniform', min: 0, max: 1 }); // 0.754\n\n// Boolean\nrandom({ mode: 'boolean' }); // true\n\n// Normal distribution\nrandom({ mode: 'normal', min: 0, max: 100 }); // 54.32\n\n// Pick from array\nrandom({ \n  mode: 'pickFromArray', \n  array: ['apple', 'banana', 'orange'] \n}); // 'banana'\n\n// All distributions\nconst formats = random({ min: 0, max: 100 });\nconsole.log(formats.uniform);    // Uniform distribution\nconsole.log(formats.normal);     // Normal distribution\nconsole.log(formats.integer);    // Integer\nconsole.log(formats.boolean);    // Boolean\n```\n\n### Date Utilities\n\n#### `formatDate(date, options)`\n\nFormat dates with various patterns.\n\n```javascript\nimport { formatDate } from '@cabdi_waaxid/utils';\n\nconst date = new Date('2023-10-15T14:30:00Z');\n\n// ISO format\nformatDate(date, { mode: 'iso' }); // '2023-10-15T14:30:00.000Z'\n\n// Locale format\nformatDate(date, { mode: 'locale' }); // '10/15/2023'\n\n// Relative time\nformatDate(new Date(Date.now() - 300000), { mode: 'relative' }); // '5 minutes ago'\n\n// Custom format\nformatDate(date, { \n  mode: 'custom', \n  pattern: 'YYYY-MM-DD HH:mm:ss' \n}); // '2023-10-15 14:30:00'\n\n// All formats\nconst formats = formatDate(date);\nconsole.log(formats.iso);      // ISO string\nconsole.log(formats.locale);   // Localized date\nconsole.log(formats.relative); // Relative time\nconsole.log(formats.custom);   // Custom format\n```\n\n## Advanced Usage\n\n### Function Composition\n\n```javascript\nimport { capitalize, truncate } from '@cabdi_waaxid/utils';\n\nconst processText = (text) => {\n  const capitalized = capitalize(text, { mode: 'titleCase' });\n  return truncate(capitalized, { mode: 'end', length: 20 });\n};\n\nprocessText('this is a very long text that needs processing');\n// 'This Is A Very Long...'\n```\n\n### Batch Processing\n\n```javascript\nimport { arrayUtils, chunk } from '@cabdi_waaxid/utils';\n\nconst processInBatches = (data, batchSize = 10) => {\n  const batches = chunk(data, { mode: 'fixed', size: batchSize });\n  \n  return batches.map(batch => \n    arrayUtils(batch, { mode: 'shuffle' })\n  );\n};\n```\n\n## Contributing\n\nWe welcome contributions!\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Cabdi Waaxid Siciid**\n\n- GitHub: [@cabdiwaaxid-so](https://github.com/cabdiwaaxid-so)\n- Email: [Cabdi Waaxid Siciid](cabdiwaaxidsiciid100@gmail.com)\n\n## Support\n\nIf you find this library useful, please give it a star on GitHub!","readmeFilename":"README.md","_rev":"1-19d6df9ff7d47fa8d3ff38361a3cd5c4"}