@mycuppa/core

The @mycuppa/core package provides essential utilities, types, and helpers that form the foundation of the Cuppa framework.

Installation

npm install @mycuppa/core
# or
pnpm add @mycuppa/core

Features

Type Utilities

Advanced TypeScript type helpers for better type safety:

import type { DeepPartial, RequireKeys, OptionalKeys } from '@mycuppa/core'

// Make all properties optional recursively
type Config = {
  api: {
    url: string
    timeout: number
  }
}

type PartialConfig = DeepPartial<Config>
// { api?: { url?: string; timeout?: number } }

// Make specific keys required
type User = {
  id?: string
  name?: string
  email?: string
}

type ValidUser = RequireKeys<User, 'id' | 'email'>
// { id: string; name?: string; email: string }

Utility Functions

Common utility functions for everyday tasks:

import { isDefined, isPlainObject, deepMerge } from '@mycuppa/core'

// Type-safe null/undefined checks
const value: string | null = getValue()
if (isDefined(value)) {
  // TypeScript knows value is string here
  console.log(value.toUpperCase())
}

// Check if value is a plain object
isPlainObject({}) // true
isPlainObject([]) // false
isPlainObject(new Date()) // false

// Deep merge objects
const defaults = { theme: { colors: { primary: '#000' } } }
const custom = { theme: { colors: { secondary: '#fff' } } }
const merged = deepMerge(defaults, custom)
// { theme: { colors: { primary: '#000', secondary: '#fff' } } }

Performance Utilities

Optimize function execution:

import { debounce, throttle } from '@mycuppa/core'

// Debounce - Execute after delay
const searchHandler = debounce((query: string) => {
  console.log('Searching for:', query)
}, 300)

searchHandler('a') // Won't execute
searchHandler('ab') // Won't execute
searchHandler('abc') // Will execute after 300ms

// Throttle - Execute at most once per interval
const scrollHandler = throttle(() => {
  console.log('Scroll position updated')
}, 100)

window.addEventListener('scroll', scrollHandler)

Helper Functions

import { sleep, generateId } from '@mycuppa/core'

// Async sleep
await sleep(1000) // Wait 1 second

// Generate unique IDs
const id1 = generateId() // "lm3k9f7-abc123"
const id2 = generateId('user') // "user-lm3k9f7-abc123"

Logger

Structured logging with configurable levels:

import { createLogger } from '@mycuppa/core'

const logger = createLogger({
  level: 'info',
  prefix: 'MyApp',
  timestamp: true,
})

logger.debug('Debug message') // Won't show (level is 'info')
logger.info('Info message') // Shows: [2024-01-01T12:00:00.000Z] [INFO] [MyApp] Info message
logger.warn('Warning message')
logger.error('Error message')

API Reference

Types

Environment - Environment types (development, staging, production, test)
LogLevel - Log levels (debug, info, warn, error)
CuppaConfig - Framework configuration interface
DeepPartial<T> - Make all properties optional recursively
RequireKeys<T, K> - Make specific keys required
OptionalKeys<T, K> - Make specific keys optional

Functions

isDefined<T>(value) - Type-safe check for non-null/undefined values
isPlainObject(value) - Check if value is a plain object
deepMerge(target, source) - Deep merge two objects
debounce(fn, delay) - Create debounced function
throttle(fn, limit) - Create throttled function
sleep(ms) - Async sleep utility
generateId(prefix?) - Generate unique IDs

Classes

Logger - Structured logging with levels and formatting

Best Practices

Use TypeScript types - Leverage the type utilities for better type safety
Debounce user input - Use debounce for search inputs and form fields
Throttle expensive operations - Use throttle for scroll/resize handlers
Structured logging - Use the Logger instead of console.log
Type guards - Use isDefined and isPlainObject for runtime type safety

Examples

See the Quick Start guide for a complete example using @mycuppa/core.