Quick Start

Get started with xfunc in minutes! This guide will help you install and use the most common utility functions.

Installation

Choose your preferred package manager:

pnpm

pnpm add xfunc

npm

npm install xfunc

yarn

yarn add xfunc

Basic Usage

xfunc supports both ESM and CommonJS imports. For optimal tree shaking, import only the functions you need:

// ✅ Recommended: Import specific functions
import { debounce, toNumber } from 'xfunc'

// ✅ Also works: Import all functions
import * as xfunc from 'xfunc'

Common Use Cases

🚀 Function Utilities

Debounce API Calls

Perfect for search inputs and form validation:

import { debounce } from 'xfunc'

const searchHandler = debounce((query: string) => {
  // API call only happens 300ms after user stops typing
  searchAPI(query)
}, 300)

// Use in your event handlers
searchInput.addEventListener('input', (e) => {
  searchHandler(e.target.value)
})

Throttle Events

Great for scroll handlers and button clicks:

import { throttle } from 'xfunc'

const scrollHandler = throttle(() => {
  console.log('Scroll event handled')
}, 100)

window.addEventListener('scroll', scrollHandler)

🔍 Type Checking

Safe and reliable type checking for any value:

import { isString, isEmpty, isNil } from 'xfunc'

// Check types safely
if (Array.isArray(data)) {
  data.forEach(item => console.log(item))
}

if (isString(userInput) && !isEmpty(userInput)) {
  processInput(userInput)
}

// Handle null/undefined
if (!isNil(value)) {
  // value is neither null nor undefined
  console.log(value)
}

📊 Array Operations

import { toArray } from 'xfunc'

// Convert anything to array
const items = toArray(userInput) // Works with strings, numbers, arrays, etc.

🔢 Number Conversion

import { toNumber } from 'xfunc'

// Safe number conversion
const age = toNumber(formData.age) // Handles strings, arrays, etc.
const price = toNumber('$1,200.50') // 0 (handles non-numeric gracefully)

🏗️ Object Manipulation

import { pick, omit, mapEntries } from 'xfunc'

const user = { 
  id: 1, 
  name: 'John', 
  email: 'john@example.com', 
  password: 'secret',
  createdAt: '2024-01-01'
}

// Extract only needed properties
const publicUser = pick(user, ['id', 'name', 'email'])
// { id: 1, name: 'John', email: 'john@example.com' }

// Remove sensitive data
const safeUser = omit(user, ['password'])

// Transform object entries
const transformed = mapEntries(user, ([key, value]) => [
  key.toUpperCase(), 
  typeof value === 'string' ? value.toUpperCase() : value
])

Real-World Examples

Form Validation with Debounce

import { debounce, isString, isEmpty } from 'xfunc'

class FormValidator {
  private validateEmail = debounce((email: string) => {
    if (!isString(email) || isEmpty(email)) {
      this.showError('Email is required')
      return
    }
    
    // Validate email format...
    this.validateEmailFormat(email)
  }, 500)

  onEmailInput(event: Event) {
    const email = (event.target as HTMLInputElement).value
    this.validateEmail(email)
  }
}

API Response Processing

import { pick, toNumber } from 'xfunc'

function processApiResponse(response: unknown) {
  if (!Array.isArray(response)) {
    throw new Error('Expected array response')
  }

  return response.map(item => ({
    ...pick(item, ['id', 'name', 'email']),
    id: toNumber(item.id), // Ensure ID is a number
  }))
}

Infinite Scroll with Throttle

import { throttle } from 'xfunc'

class InfiniteScroll {
  private loadMore = throttle(() => {
    if (this.isNearBottom() && !this.loading) {
      this.fetchNextPage()
    }
  }, 200)

  init() {
    window.addEventListener('scroll', this.loadMore)
  }
}

Next Steps

• 📚 Explore the complete API reference
• 🎯 Check out more examples and patterns
• 🔧 Learn about advanced usage
• 💡 See CI/CD integration guide for production apps

TypeScript Support

xfunc is built with TypeScript and provides excellent type safety out of the box:

import { pick } from 'xfunc'

function processData<T>(data: T) {
  if (Array.isArray(data)) {
    // TypeScript knows data is an array here
    return data.map(item => item)
  }
  
  // Type-safe object operations
  const result = pick(data as Record<string, unknown>, ['id', 'name'])
  return result
}

Ready to dive deeper? Check out our API documentation for complete function references and advanced usage patterns.