ts-buildkit

A comprehensive TypeScript utility library providing 100+ helper functions for modern web development. Built with full TypeScript support, tree-shaking capabilities, and designed to work seamlessly in both Node.js and browser environments.

📚 Documentation

• 📖 API Documentation - Complete API reference with examples for all 100+ functions
• 🔧 API Reference - Quick reference guide for common utilities
• 🚀 Contributing Guide - Guidelines for contributors
• 📝 Changelog - Version history and updates
• 🗺️ Roadmap - Future plans and upcoming features
• 🔒 Security Policy - Security guidelines and reporting

✨ Key Features

🎯 Core Features

• 100+ Utility Functions: String manipulation, validation, date formatting, array/object utilities, and more
• TypeScript First: Built with TypeScript, full type definitions, and strict mode enabled
• Tree-Shakeable: Import only what you need for minimal bundle size
• Cross-Platform: Works seamlessly in Node.js (>=22.2.0) and all modern browsers
• Zero Core Dependencies: No external dependencies for core utilities
• Configurable Options: All functions support customizable options with sensible defaults

📦 Modular Architecture

• Main Module: Core utilities via ts-buildkit
• Gaming Module: ts-buildkit/play-and-win - Gaming types and utilities
• Roommate Module: ts-buildkit/roommate - Roommate finding functionality
• Optional Packages: ts-buildkit/require-package/{crypto-js,dayjs,zod} - Wrapped peer dependencies

🔧 Advanced Capabilities

• Cryptography: AES encryption/decryption with configurable secrets
• Validation: Email, URL, phone, file upload, and custom validators
• Permissions: Role-based access control with permission checking
• Mobile Ready: Built-in Capacitor support for mobile apps
• Error Handling: Comprehensive error types and handlers
• Platform Detection: Automatic platform and device detection

Installation

npm install ts-buildkit
# or
yarn add ts-buildkit
# or
pnpm add ts-buildkit

Optional Peer Dependencies

Some features require additional packages. Install only what you need:

# For cryptography features
npm install crypto-js

# For advanced date handling
npm install dayjs

# For validation schemas
npm install zod

Quick Start

import {
  isValidEmail,
  formatUSD,
  generateSlug,
  generateUUID,
} from 'ts-buildkit';

// Validate email
if (isValidEmail('[email protected]')) {
  console.log('Valid email!');
}

// Format currency
const price = formatUSD(1234.56); // '$1,234.56'

// Generate URL-friendly slugs
const slug = generateSlug('Hello World!'); // 'hello-world'

// Generate unique identifiers
const id = generateUUID(); // '550e8400-e29b-41d4-a716-446655440000'

Configuration

Cryptography Setup

If using cryptography utilities, configure the library first:

import { configureZTK } from 'ts-buildkit';

// Initialize with your secret key
configureZTK({
  cryptoSecret: process.env.CRYPTO_SECRET || 'your-secret-key',
});

// Now you can use crypto functions
import { encryptData, decryptData } from 'ts-buildkit';

const encrypted = encryptData('sensitive information');
const decrypted = decryptData(encrypted);

Core Modules

String Utilities

import {
  convertToTitleCase,
  truncateString,
  formatCamelCaseToTitle,
  removeLeadingTrailingChars,
} from 'ts-buildkit';

convertToTitleCase('hello world'); // 'Hello world'
truncateString('Long text here', 10); // 'Long text...'
formatCamelCaseToTitle('helloWorld'); // 'Hello World'
removeLeadingTrailingChars('/path/', '/'); // 'path'

Validation

import {
  validateEmail,
  validatePhoneNumber,
  validateURL,
  isZNonEmptyString,
} from 'ts-buildkit';

// Email validation with domain restriction
validateEmail('[email protected]', ['company.com']); // true

// Phone number validation
const phone = validatePhoneNumber('+1234567890');
// { isValid: true, formatted: '+1 234-567-890' }

// URL validation
const url = validateURL('https://example.com');
// { isValid: true }

// String validation
isZNonEmptyString('hello'); // true

Array Operations

import {
  flattenArray,
  checkEqualityOfTwoArray,
  arrayMoveImmutable,
} from 'ts-buildkit';

flattenArray([
  [1, 2],
  [3, 4],
]); // [1, 2, 3, 4]
checkEqualityOfTwoArray(['a', 'b'], ['b', 'a']); // true
arrayMoveImmutable(['a', 'b', 'c'], 0, 2); // ['b', 'c', 'a']

Object Utilities

import {
  isObject,
  getObjectKey,
  isEqual,
  buildFilterObject,
} from 'ts-buildkit';

isObject({ a: 1 }); // true
getObjectKey({ a: 1, b: 2 }, 2); // 'b'
isEqual({ a: 1 }, { a: 1 }); // true
buildFilterObject({ a: 1, b: null }); // { a: 1 }

Date & Time

import {
  dayjs,
  getTimeInUnit,
  getRemainingTimeForCountDown,
  TimeUnitEnum,
} from 'ts-buildkit';

// Using dayjs
const tomorrow = dayjs().add(1, 'day').format('YYYY-MM-DD');

// Convert time units
getTimeInUnit(3600000, TimeUnitEnum.HOURS); // 1

// Countdown timer
const remaining = getRemainingTimeForCountDown('2024-12-31');
// { days: 45, hours: 12, minutes: 30, seconds: 15 }

Image Handling

import {
  imageUrlToBase64,
  getImageDimensions,
  getImageAspectRatio,
  validateFileBeforeUpload,
} from 'ts-buildkit';

// Convert image URL to base64
const base64 = await imageUrlToBase64('https://example.com/image.jpg');

// Get image dimensions
const dims = await getImageDimensions(imageFile);
// { width: 1920, height: 1080 }

// Calculate aspect ratio
const ratio = await getImageAspectRatio(imageFile); // 1.777...

// Validate file before upload
const validation = validateFileBeforeUpload(file, {
  maxSize: 5 * 1024 * 1024, // 5MB
  allowedTypes: ['image/jpeg', 'image/png'],
});

Permissions & Roles

import {
  hasPermission,
  validateUserPermissions,
  RoleEnum,
  PermissionEnum,
} from 'ts-buildkit';

const userPermissions = ['read', 'write'];

// Check single permission
hasPermission(userPermissions, 'read'); // true

// Validate multiple permissions
validateUserPermissions({
  userPermissions,
  requiredPermissions: ['read'],
  excludedPermissions: ['admin'],
  checkMode: 'AND',
}); // true

Specialized Modules

Gaming Module

For gaming and gambling applications:

import {
  GameTypeEnum,
  IGame,
  IGameRoom,
  TransactionTypeEnum,
} from 'ts-buildkit/play-and-win';

// Use gaming-specific types and utilities
const game: IGame = {
  id: '123',
  type: GameTypeEnum.POKER,
  minPlayers: 2,
  maxPlayers: 6,
  // ...
};

Roommate Module

For roommate finding applications:

import {
  GenderEnum,
  IPlace,
  IRoommateUser,
  CleanlinessEnum,
} from 'ts-buildkit/roommate';

// Use roommate-specific types
const user: IRoommateUser = {
  id: '123',
  gender: GenderEnum.FEMALE,
  lifestyle: {
    cleanliness: CleanlinessEnum.VERY_TIDY,
    // ...
  },
};

Enums Reference

The library provides extensive enums for type safety:

import {
  RequestTypeEnum,
  ResponseStatusEnum,
  TimeUnitEnum,
  BooleanEnum,
} from 'ts-buildkit';

// HTTP methods
RequestTypeEnum.GET; // 'GET'
RequestTypeEnum.POST; // 'POST'

// Response statuses
ResponseStatusEnum.SUCCESS; // 'success'
ResponseStatusEnum.ERROR; // 'error'

// Time units
TimeUnitEnum.HOURS; // 'hours'
TimeUnitEnum.DAYS; // 'days'

// Boolean strings
BooleanEnum.TRUE; // 'true'
BooleanEnum.FALSE; // 'false'

Type Definitions

The library exports comprehensive TypeScript types:

import type {
  IGenericObject,
  IPaginationOptions,
  IDefaultDBColumns,
  GeolocationCoordinates,
} from 'ts-buildkit';

// Use in your interfaces
interface User extends IDefaultDBColumns {
  name: string;
  email: string;
}

// Pagination
const options: IPaginationOptions = {
  page: 1,
  limit: 20,
};

Error Handling

Built-in error handling utilities:

import {
  reportCustomError,
  getStripeErrorMessageByErrorCode,
} from 'ts-buildkit';

try {
  // Your code
} catch (error) {
  reportCustomError(error, 'Payment processing failed');
}

// Stripe error handling
const message = getStripeErrorMessageByErrorCode('card_declined');
// 'Your card was declined. Please try another payment method.'

Platform Detection

Detect device and platform:

import {
  detectDeviceAndViewMode,
  PlatformTypeEnum,
  CapacitorPlatformEnum,
} from 'ts-buildkit';

const device = detectDeviceAndViewMode();
// { isMobile: false, isTablet: false, isDesktop: true }

Constants

Access predefined constants:

import {
  apiConstants,
  dateFormat,
  mediaScales,
  allowedImageTypes,
} from 'ts-buildkit';

// API defaults
apiConstants.defaultTimeout; // 30000

// Date formats
dateFormat.standard; // 'YYYY-MM-DD'

// Media breakpoints
mediaScales.mobile; // { min: 0, max: 767 }

// Allowed image types
allowedImageTypes; // ['image/jpeg', 'image/png', ...]

Best Practices

1. Import Only What You Need

// ✅ Good - specific imports for tree shaking
import { isValidEmail, formatUSD } from 'ts-buildkit';

// ❌ Avoid - imports entire library
import * as buildkit from 'ts-buildkit';

2. Configure Before Using Crypto

// ✅ Configure first
import { configureZTK, encryptData } from 'ts-buildkit';

configureZTK({ cryptoSecret: 'secret' });
const encrypted = encryptData('data');

// ❌ Don't use crypto without configuration
const encrypted = encryptData('data'); // Will throw error

3. Use Type Guards

import { isZNonEmptyString, isZValidNumber } from 'ts-buildkit';

function processInput(input: unknown) {
  if (isZNonEmptyString(input)) {
    // TypeScript knows input is string
    return input.toUpperCase();
  }

  if (isZValidNumber(input)) {
    // TypeScript knows input is number
    return input * 2;
  }
}

4. Leverage Enums for Type Safety

import { RequestTypeEnum, ResponseStatusEnum } from 'ts-buildkit';

// ✅ Use enums
function makeRequest(method: RequestTypeEnum) {
  // Type safe
}

// ❌ Avoid magic strings
function makeRequest(method: string) {
  // Not type safe
}

API Documentation

For detailed documentation of all functions, see API_DOCUMENTATION.md

Development

Requirements

• Node.js >= 22.2.0
• TypeScript >= 5.0

Setup

# Clone the repository
git clone https://github.com/zaions/ts-buildkit.git
cd ts-buildkit

# Install dependencies
yarn install

# Run development mode
yarn dev

# Run tests
yarn test

# Build the library
yarn build

# Format code
yarn prettier

Project Structure

ts-buildkit/
├── src/
│   ├── utils/          # Core utility functions
│   ├── enums/          # Enumeration definitions
│   ├── types/          # TypeScript type definitions
│   ├── configure/      # Configuration utilities
│   ├── play-and-win/   # Gaming module
│   ├── roommate/       # Roommate module
│   └── packages/       # External package utilities
├── tests/              # Test files
└── dist/              # Built output

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📚 Full Documentation
• 🐛 Report Issues
• 💬 Discussions

Acknowledgments

Built with ❤️ by the Zaions team.

For more examples and detailed API documentation, visit our comprehensive API guide.