The foundational package of the Gen2Code framework, providing shared utilities, types, configurations, and React hooks for building modern web applications.

🚀 Installation

npm install @gen2code/core
# or
yarn add @gen2code/core
# or
pnpm add @gen2code/core

📋 Table of Contents

🏗️ Types

Comprehensive TypeScript type definitions for the Gen2Code framework.

Authentication Types

import type { 
  AuthUser, 
  AuthSession, 
  Permission, 
  Role,
  AuthProvider 
} from '@gen2code/core';

const user: AuthUser = {
  id: 'user-123',
  email: 'user@example.com',
  emailVerified: true,
  // ... other properties
};

const session: AuthSession = {
  user,
  accessToken: 'token',
  refreshToken: 'refresh',
  expiresAt: new Date(),
  // ... other properties
};

User Management Types

import type { 
  User, 
  UserProfile, 
  UserSettings, 
  UserRole,
  Avatar 
} from '@gen2code/core';

const userProfile: UserProfile = {
  firstName: 'John',
  lastName: 'Doe',
  bio: 'Software Developer',
  avatar: {
    url: 'https://example.com/avatar.jpg',
    alt: 'John Doe'
  }
};

Team Management Types

import type { 
  Team, 
  TeamMember, 
  TeamInvitation, 
  TeamRole,
  TeamPermission 
} from '@gen2code/core';

const team: Team = {
  id: 'team-123',
  name: 'Development Team',
  slug: 'dev-team',
  // ... other properties
};

API Types

import type { 
  ApiResponse, 
  ApiError, 
  PaginatedResponse, 
  RequestConfig 
} from '@gen2code/core';

const response: ApiResponse<User[]> = {
  data: users,
  success: true,
  message: 'Users retrieved successfully'
};

✅ Validation

Comprehensive validation utilities with TypeScript support and detailed error reporting.

Email Validation

import { 
  validateEmail, 
  normalizeEmail, 
  extractEmailDomain,
  isDisposableEmail,
  validateEmailDomain 
} from '@gen2code/core';

// Basic email validation
const isValid = validateEmail('user@example.com'); // true

// Normalize email (lowercase, trim)
const normalized = normalizeEmail('  USER@EXAMPLE.COM  '); // 'user@example.com'

// Extract domain
const domain = extractEmailDomain('user@example.com'); // 'example.com'

// Check for disposable email providers
const isDisposable = isDisposableEmail('user@tempmail.com'); // true

// Validate specific domains
const isDomainValid = validateEmailDomain('example.com', {
  allowedDomains: ['example.com', 'company.com']
}); // true

Password Validation

import { 
  validatePassword, 
  getPasswordStrengthDescription,
  getPasswordStrengthColor,
  generatePasswordSuggestions,
  detectPasswordPatterns,
  estimatePasswordCrackTime 
} from '@gen2code/core';

// Comprehensive password validation
const result = validatePassword('MySecurePassword123!', {
  minLength: 8,
  requireUppercase: true,
  requireLowercase: true,
  requireNumbers: true,
  requireSymbols: true,
  maxLength: 128
});

console.log(result.isValid); // true
console.log(result.strength); // 0-5 strength score
console.log(result.feedback); // Array of feedback messages

// Get human-readable strength description
const description = getPasswordStrengthDescription(result.strength); // 'Very Strong'

// Get color for UI display
const color = getPasswordStrengthColor(result.strength); // '#22c55e'

// Generate improvement suggestions
const suggestions = generatePasswordSuggestions('weak123');
// ['Add uppercase letters', 'Add symbols', 'Increase length']

// Detect common patterns
const patterns = detectPasswordPatterns('password123');
// ['common_word', 'sequential_numbers']

// Estimate crack time
const crackTime = estimatePasswordCrackTime('MySecurePassword123!');
// { seconds: 1.2e+15, display: 'centuries' }

URL and Phone Validation

import { validateUrl, validatePhone } from '@gen2code/core';

// URL validation with protocol checking
const isValidUrl = validateUrl('https://example.com', {
  protocols: ['http', 'https'],
  requireProtocol: true
}); // true

// International phone number validation
const isValidPhone = validatePhone('+1-555-123-4567', {
  country: 'US',
  format: 'international'
}); // true

Field Validation

import { 
  validateRequired,
  validateLength,
  validateRange,
  validateArray,
  validateObject,
  validateEnum,
  validateDate,
  validateBoolean,
  validateFields 
} from '@gen2code/core';

// Individual field validation
const requiredResult = validateRequired('value'); // { isValid: true }
const lengthResult = validateLength('hello', { min: 3, max: 10 }); // { isValid: true }
const rangeResult = validateRange(25, { min: 18, max: 65 }); // { isValid: true }

// Validate multiple fields at once
const fieldsResult = validateFields({
  email: { value: 'user@example.com', validators: ['required', 'email'] },
  age: { value: 25, validators: ['required', { type: 'range', min: 18, max: 65 }] }
});

Schema Validation

import { 
  validateSchema,
  validateSchemaSafe,
  createEmailSchema,
  createPasswordSchema,
  createUserRegistrationSchema,
  createUserLoginSchema,
  createTeamSchema 
} from '@gen2code/core';

// Use pre-built schemas
const registrationSchema = createUserRegistrationSchema();
const result = validateSchema(registrationSchema, {
  email: 'user@example.com',
  password: 'SecurePassword123!',
  firstName: 'John',
  lastName: 'Doe'
});

if (result.isValid) {
  console.log('Valid user data:', result.data);
} else {
  console.log('Validation errors:', result.errors);
}

// Safe validation (doesn't throw)
const safeResult = validateSchemaSafe(registrationSchema, userData);

// Create custom schemas
const emailSchema = createEmailSchema({
  allowedDomains: ['company.com'],
  blockDisposable: true
});

const passwordSchema = createPasswordSchema({
  minLength: 12,
  requireSymbols: true
});

🎨 Formatting

Utilities for formatting dates, numbers, text, and other data types.

Date and Time Formatting

import { formatDate, formatRelativeTime } from '@gen2code/core';

// Format dates with timezone support
const formatted = formatDate(new Date(), {
  format: 'yyyy-MM-dd HH:mm:ss',
  timezone: 'America/New_York',
  locale: 'en-US'
}); // '2024-01-15 14:30:00'

// Relative time formatting
const relative = formatRelativeTime(new Date(Date.now() - 3600000)); // '1 hour ago'

Number and Currency Formatting

import { 
  formatNumber, 
  formatCurrency, 
  formatFileSize,
  formatPercentage 
} from '@gen2code/core';

// Number formatting with locale support
const number = formatNumber(1234567.89, {
  locale: 'en-US',
  minimumFractionDigits: 2
}); // '1,234,567.89'

// Currency formatting
const price = formatCurrency(99.99, {
  currency: 'USD',
  locale: 'en-US'
}); // '$99.99'

// File size formatting
const size = formatFileSize(1024 * 1024 * 2.5); // '2.5 MB'

// Percentage formatting
const percent = formatPercentage(0.1234, { decimals: 2 }); // '12.34%'

Text Formatting

import { 
  truncateText, 
  generateSlug, 
  capitalizeWords,
  formatInitials,
  formatPhoneNumber 
} from '@gen2code/core';

// Text truncation with ellipsis
const truncated = truncateText('This is a very long text', {
  maxLength: 20,
  ellipsis: '...'
}); // 'This is a very long...'

// URL-friendly slug generation
const slug = generateSlug('Hello World! This is a Test'); // 'hello-world-this-is-a-test'

// Capitalize words
const capitalized = capitalizeWords('hello world'); // 'Hello World'

// Generate initials
const initials = formatInitials('John Doe Smith'); // 'JDS'

// Format phone numbers
const phone = formatPhoneNumber('+15551234567', {
  format: 'national'
}); // '(555) 123-4567'

🔐 Cryptography

Secure cryptographic utilities for password hashing, data encryption, and token generation.

Password Hashing

import { 
  hashPassword, 
  verifyPassword, 
  generateSalt 
} from '@gen2code/core';

// Hash password with automatic salt generation
const hashedPassword = await hashPassword('userPassword123');

// Verify password against hash
const isValid = await verifyPassword('userPassword123', hashedPassword); // true

// Generate custom salt
const salt = generateSalt(16); // 16-byte salt

Data Encryption

import { 
  encryptData, 
  decryptData, 
  generateEncryptionKey 
} from '@gen2code/core';

// Generate encryption key
const key = generateEncryptionKey();

// Encrypt sensitive data
const encrypted = encryptData('sensitive information', key);

// Decrypt data
const decrypted = decryptData(encrypted, key); // 'sensitive information'

Token and String Generation

import { 
  generateToken, 
  generateSecureString,
  generateChecksum,
  verifyChecksum,
  constantTimeCompare 
} from '@gen2code/core';

// Generate secure tokens
const token = generateToken(32); // 32-byte random token
const secureString = generateSecureString(16); // 16-character secure string

// Generate and verify checksums
const data = 'important data';
const checksum = generateChecksum(data);
const isValid = verifyChecksum(data, checksum); // true

// Constant-time string comparison (prevents timing attacks)
const isEqual = constantTimeCompare('secret1', 'secret2'); // false

⚙️ Configuration Management

Comprehensive configuration management system with environment variable handling and validation.

Configuration Manager

import { 
  ConfigManager, 
  config, 
  getConfig,
  getConfigValue,
  updateConfig,
  validateConfig,
  initializeConfig 
} from '@gen2code/core';

// Initialize configuration
await initializeConfig({
  environment: 'development',
  configPath: './config'
});

// Get configuration values
const dbConfig = getConfig('database');
const apiUrl = getConfigValue('api.baseUrl', 'http://localhost:3000');

// Update configuration
await updateConfig('features.enableNewUI', true);

// Validate configuration
const validation = validateConfig();
if (!validation.isValid) {
  console.error('Configuration errors:', validation.errors);
}

Environment Variable Management

import { 
  EnvManager,
  env,
  getEnvString,
  getEnvNumber,
  getEnvBoolean,
  getEnvArray,
  getEnvJson,
  getEnvUrl,
  loadEnvFiles,
  getCurrentEnvironment,
  isDevelopment,
  isProduction 
} from '@gen2code/core';

// Load environment files
await loadEnvFiles(['.env', '.env.local']);

// Get typed environment variables
const dbUrl = getEnvString('DATABASE_URL', 'postgresql://localhost:5432/db');
const port = getEnvNumber('PORT', 3000);
const enableFeature = getEnvBoolean('ENABLE_FEATURE', false);
const allowedOrigins = getEnvArray('ALLOWED_ORIGINS', []);
const config = getEnvJson('APP_CONFIG', {});
const apiUrl = getEnvUrl('API_URL');

// Environment detection
const currentEnv = getCurrentEnvironment(); // 'development' | 'production' | 'test' | 'staging'
const isDev = isDevelopment(); // true in development
const isProd = isProduction(); // true in production

⚛️ React Hooks

Production-ready React hooks for common functionality.

API Hooks

import { 
  useApi, 
  useMutation, 
  useQuery, 
  usePagination,
  useWebSocket 
} from '@gen2code/core';

// Generic API hook with loading states
const { data, loading, error, execute } = useApi<User[]>({
  url: '/api/users',
  method: 'GET'
});

// Mutation hook for data modifications
const { mutate, loading: mutating } = useMutation<User>({
  url: '/api/users',
  method: 'POST',
  onSuccess: (user) => console.log('User created:', user),
  onError: (error) => console.error('Failed to create user:', error)
});

// Query hook with caching
const { data: users, refetch } = useQuery<User[]>({
  queryKey: 'users',
  url: '/api/users',
  cacheTime: 5 * 60 * 1000 // 5 minutes
});

// Pagination hook
const { 
  data, 
  currentPage, 
  totalPages, 
  nextPage, 
  prevPage, 
  goToPage 
} = usePagination<User>({
  url: '/api/users',
  pageSize: 20
});

// WebSocket hook
const { 
  data, 
  sendMessage, 
  readyState, 
  connect, 
  disconnect 
} = useWebSocket('ws://localhost:8080', {
  onMessage: (message) => console.log('Received:', message),
  reconnectAttempts: 3
});

Authentication Hooks

import { 
  useAuth, 
  useSession, 
  usePermissions,
  useAuthRedirect,
  useAuthForm 
} from '@gen2code/core';

// Authentication state management
const { 
  user, 
  isAuthenticated, 
  login, 
  logout, 
  register,
  loading 
} = useAuth();

// Session management
const { 
  session, 
  refreshSession, 
  clearSession,
  isExpired 
} = useSession();

// Permission checking
const { 
  hasPermission, 
  hasRole, 
  canAccess,
  permissions 
} = usePermissions();

// Automatic redirect for protected routes
useAuthRedirect({
  redirectTo: '/login',
  requireAuth: true,
  requiredRoles: ['admin']
});

// Form handling for auth forms
const { 
  formData, 
  errors, 
  isValid, 
  handleChange, 
  handleSubmit,
  reset 
} = useAuthForm({
  initialData: { email: '', password: '' },
  validationSchema: loginSchema,
  onSubmit: async (data) => await login(data)
});

Utility Hooks

import { 
  useLocalStorage, 
  useDebounce,
  useTheme,
  useMediaQuery,
  useClipboard 
} from '@gen2code/core';

// Local storage with TypeScript support
const [user, setUser] = useLocalStorage<User>('user', null);

// Debounce values and callbacks
const debouncedValue = useDebounce(searchTerm, 500);
const debouncedCallback = useDebounceCallback(
  (query: string) => searchUsers(query),
  300
);

// Theme management
const { 
  theme, 
  setTheme, 
  resolvedTheme,
  systemTheme 
} = useTheme();

// Media queries and responsive design
const isMobile = useMediaQuery('(max-width: 768px)');
const { isMobile: mobile, isTablet, isDesktop } = useBreakpoints();

// Clipboard operations
const { 
  copy, 
  copied, 
  copyFormatted,
  isSupported 
} = useClipboard({
  timeout: 2000
});

// Usage
await copy('Text to copy');
console.log(copied); // true for 2 seconds

🌐 API Utilities

Comprehensive API utilities with error handling, caching, and retry logic.

HTTP Client

import { 
  createHttpClient,
  HttpApiError,
  NetworkError,
  handleApiError 
} from '@gen2code/core';

// Create configured HTTP client
const client = createHttpClient({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  retries: 3,
  headers: {
    'Authorization': 'Bearer token'
  }
});

// Make requests with automatic error handling
try {
  const response = await client.get<User[]>('/users');
  console.log(response.data);
} catch (error) {
  if (error instanceof HttpApiError) {
    console.error('API Error:', error.message, error.statusCode);
  } else if (error instanceof NetworkError) {
    console.error('Network Error:', error.message);
  }
}

Caching and Retry Logic

import { 
  createCache,
  createRetryConfig,
  isRetryableError 
} from '@gen2code/core';

// Create cache instance
const cache = createCache({
  maxSize: 100,
  ttl: 5 * 60 * 1000 // 5 minutes
});

// Cache API responses
cache.set('users', usersData);
const cachedUsers = cache.get('users');

// Retry configuration
const retryConfig = createRetryConfig({
  attempts: 3,
  delay: 1000,
  backoff: 'exponential',
  retryCondition: (error) => isRetryableError(error)
});

🚨 Error Handling

Comprehensive error handling system with logging, reporting, and user-friendly messages.

Error Classes

import { 
  AppError,
  ValidationError,
  AuthenticationError,
  AuthorizationError,
  HttpApiError 
} from '@gen2code/core';

// Create custom application errors
throw new AppError('Something went wrong', 'APP_ERROR', {
  userId: '123',
  action: 'updateProfile'
});

// Validation errors with field details
throw new ValidationError('Invalid input', {
  email: ['Invalid email format'],
  password: ['Password too weak']
});

// Authentication errors
throw new AuthenticationError('Invalid credentials', 'INVALID_CREDENTIALS');

// Authorization errors
throw new AuthorizationError('Insufficient permissions', 'INSUFFICIENT_PERMISSIONS');

Error Logging and Reporting

import { 
  ErrorLogger,
  logError,
  logWarn,
  logInfo,
  reportError,
  createUserFriendlyError 
} from '@gen2code/core';

// Log errors with context
logError('Database connection failed', {
  database: 'users',
  host: 'localhost',
  port: 5432
});

// Log warnings and info
logWarn('API rate limit approaching');
logInfo('User logged in successfully');

// Report errors to external service
await reportError(error, {
  userId: '123',
  userAgent: navigator.userAgent,
  url: window.location.href
});

// Create user-friendly error messages
const friendlyError = createUserFriendlyError(error);
console.log(friendlyError.message); // User-friendly message
console.log(friendlyError.actions); // Suggested actions

📚 TypeScript Support

This package is built with TypeScript and provides comprehensive type definitions:

Strict Type Safety: All functions and utilities are fully typed
Generic Support: Many utilities support generic types for flexibility
Type Guards: Built-in type checking utilities
Interface Definitions: Complete interfaces for all data structures
Enum Types: Predefined enums for common values

// Example of generic type support
import type { ApiResponse, PaginatedResponse } from '@gen2code/core';

interface CustomData {
  id: string;
  name: string;
}

// Fully typed API response
const response: ApiResponse<CustomData[]> = await fetchData();

// Fully typed paginated response
const paginatedResponse: PaginatedResponse<CustomData> = await fetchPaginatedData();

🧪 Testing

The package includes comprehensive test coverage:

67 test suites with 1,214 individual tests
100% code coverage for all exported functions
Integration tests for complex workflows
Performance tests for critical utilities
Edge case testing for robust error handling

Running Tests

# Run all tests
pnpm test

# Run tests with coverage
pnpm test --coverage

# Run specific test suite
pnpm test validation

# Watch mode for development
pnpm test --watch

🤝 Contributing

This package is part of the Gen2Code framework. Please refer to the main repository for contribution guidelines.

📄 License

MIT License - see the LICENSE file for details.

@gen2code/api-framework - API documentation and standards
@gen2code/access-control - Authentication and authorization
@gen2code/user-management - User profiles and settings
@gen2code/team-management - Multi-tenant organization management

Built with ❤️ by the Gen2Code team

Keywords

FAQs

What is @gen2code/core?

Is @gen2code/core popular?

Is @gen2code/core well maintained?

Package last updated on 28 Sep 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@gen2code/core