A comprehensive, lightweight utility library

🚀 Features

• 🌳 Tree-shakable: Import only what you need for optimal bundle size
• 📦 Zero dependencies: Lightweight core with no external deps
• ⚡ High performance: Optimized implementations inspired by lodash
• 🔒 Type-safe: Full TypeScript support with detailed type definitions
• 📚 Comprehensive: 100+ utility functions across multiple categories

📦 Installation

npm install generic-functions.mlai

yarn add generic-functions.mlai

pnpm add generic-functions.mlai

🏗️ Project Structure

src/
├── core/                    # Core utility modules
│   ├── array.ts            # Array manipulation utilities
│   ├── collection.ts       # Collection utilities (arrays & objects)
│   ├── date.ts             # Date/time utilities
│   ├── function.ts         # Function utilities (debounce, throttle, etc.)
│   ├── math.ts             # Mathematical operations
│   ├── number.ts           # Number parsing and manipulation
│   ├── object.ts           # Object manipulation utilities
│   ├── string.ts           # String manipulation utilities
│   ├── type.ts             # Type checking utilities
│   ├── utility.ts          # General utility functions
│   └── index.ts            # Core module exports
├── utils/                   # Optional heavy utilities
│   └── index.ts            # Utils module exports
├── constants/               # Useful constants and patterns
│   └── index.ts            # Constants exports
└── index.ts                # Main entry point

🎯 Usage Examples

Import Usage (Tree-shakable with tsup)

Import functions directly from the main package - tsup automatically handles tree-shaking:

// All utilities are available from the main package
import { 
  // String utilities
  trim, capitalize, purify, camelCase,
  // Array utilities  
  sort, getUnique, chunk, flatten,
  // Date utilities
  formatDate, now, addTime, isBetween,
  // Object utilities
  get, set, merge, pick, omit,
  // Math utilities
  sum, mean, clamp, random,
  // Type checking
  isString, isArray, isObject, isFunction,
  // Function utilities
  debounce, throttle, memoize, curry
} from 'generic-functions.mlai';

// Usage examples
console.log(trim('  hello world  ')); // 'hello world'
console.log(capitalize('hello')); // 'Hello'
console.log(formatDate(new Date(), 'DD/MM/YYYY')); // '25/12/2023'
console.log(sum([1, 2, 3, 4])); // 10
console.log(get({ a: { b: { c: 42 } } }, 'a.b.c')); // 42

Alternative import patterns

// Import everything (not recommended for production)
import * as gf from 'generic-functions.mlai';

console.log(gf.trim('  hello world  ')); // 'hello world'
console.log(gf.formatDate(new Date(), 'DD/MM/YYYY')); // '25/12/2023'
console.log(gf.debounce(() => console.log('debounced!'), 300));

📋 API Reference

All functions are available as named imports from the main package:

import { functionName } from 'generic-functions.mlai';

String Utilities

| Function | Description | Example | |----------|-------------|---------| | purify(str) | Removes accents from string | purify('café') → 'cafe' | | capitalize(str) | Capitalizes first character | capitalize('hello') → 'Hello' | | camelCase(str) | Converts to camelCase | camelCase('hello world') → 'helloWorld' | | kebabCase(str) | Converts to kebab-case | kebabCase('Hello World') → 'hello-world' | | trim(str, chars?) | Trims whitespace or specified chars | trim(' hello ') → 'hello' |

Array Utilities

| Function | Description | Example | |----------|-------------|---------| | chunk(array, size) | Creates chunks of specified size | chunk([1,2,3,4], 2) → [[1,2], [3,4]] | | flatten(array) | Flattens array one level | flatten([1, [2, 3]]) → [1, 2, 3] | | uniq(array) | Removes duplicates | uniq([1, 2, 2, 3]) → [1, 2, 3] | | difference(array, values) | Array difference | difference([1,2,3], [2,3]) → [1] |

Object Utilities

| Function | Description | Example | |----------|-------------|---------| | get(obj, path, default?) | Gets value at path | get({a:{b:1}}, 'a.b') → 1 | | set(obj, path, value) | Sets value at path | set({}, 'a.b', 1) → {a:{b:1}} | | merge(target, ...sources) | Deep merge objects | merge({a:1}, {b:2}) → {a:1,b:2} | | pick(obj, ...keys) | Pick specified properties | pick({a:1,b:2}, 'a') → {a:1} |

Math Utilities

| Function | Description | Example | |----------|-------------|---------| | sum(numbers) | Sum of array | sum([1,2,3]) → 6 | | mean(numbers) | Average of array | mean([1,2,3]) → 2 | | clamp(num, min, max) | Clamps number to range | clamp(10, 0, 5) → 5 | | random(min?, max?) | Random number in range | random(1, 10) → 7.23... |

Date Utilities

| Function | Description | Example | |----------|-------------|---------| | formatDate(date, format) | Format date with pattern | formatDate(new Date(), 'DD/MM/YYYY') | | addTime(date, amount, unit) | Add time to date | addTime(date, 5, 'day') | | isBetween(date, start, end) | Check if date in range | isBetween(date, start, end) |

Function Utilities

| Function | Description | Example | |----------|-------------|---------| | debounce(fn, wait) | Debounce function calls | debounce(fn, 300) | | throttle(fn, wait) | Throttle function calls | throttle(fn, 100) | | memoize(fn) | Memoize function results | memoize(expensiveFn) | | curry(fn) | Curry function arguments | curry(fn)(a)(b)(c) |

🔧 Development

Prerequisites

• Node.js 16+
• TypeScript 4.5+

Setup

# Clone the repository
git clone https://github.com/Mathieu-ai/generic-functions.git
cd generic-functions

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (when available)
npm test

Build Process

# Clean dist folder
npm run clean

# Build TypeScript
npm run build

# Copy additional files
npm run copy-files

# Full build process
npm run prepare-dist

Project Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run clean | Remove dist folder | | npm run copy-files | Copy package.json and other files to dist | | npm run prepare-dist | Full build process | | npm run prepare | Pre-publish build |

🚀 Migration from v0.x

The new version uses tsup for optimal bundling and tree-shaking. All imports should now come from the main package:

Before (v0.x with subpaths):

import { api, now } from 'generic-functions.mlai/core/date';
import { trim } from 'generic-functions.mlai/core/string';

After (v0.9+ with tsup):

// Import everything from the main package - tsup handles tree-shaking automatically
import { now, trim, api } from 'generic-functions.mlai';

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes with proper TypeScript types
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. Submit a pull request

Code Style

• Use TypeScript with strict type checking
• Follow existing code patterns and naming conventions
• Add JSDoc comments for all public functions
• Include usage examples in documentation

📄 License

This project is MIT licensed.

🔗 Links

• npm package
• GitHub repository
• Issues

Made with ❤️ by Mathieu AI