@platformrocks/raffle

A CLI tool for running raffles via the terminal with CSV/TXT input, column parsing, and animated effects.

Installation

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Optionally link for global usage
npm link

Usage

Basic Commands

# Show help
raffle --help

# Show version
raffle --version
raffle version

# Run a raffle
raffle run <file> [options]

Running Raffles

With CSV Files (with headers)

# Select 1 winner from a specific column
raffle run "C:\path\to\participants.csv" --header --column name

# Select multiple winners
raffle run "C:\path\to\participants.csv" --header --column name --winners 3

# Specify custom delimiter
raffle run "C:\path\to\participants.csv" --header --column name --delimiter ";"

With Plain Text Files

# Select 1 winner from a list of names
raffle run "C:\path\to\names.txt"

# Select multiple winners
raffle run "C:\path\to\names.txt" --winners 5

Command Options

• <file> - Input file path (CSV or TXT) - supports both absolute and relative paths
• -c, --column <name> - Column name for participant names (CSV with headers)
• -h, --header - File has header row (default: false)
• -d, --delimiter <char> - Delimiter character for CSV (auto-detected if not specified)
• -w, --winners <count> - Number of winners to select (default: 1)
• --show-index - Show row indices in output (default: false)
• --countdown <seconds> - Countdown duration in seconds (default: "3")
• --no-animation - Disable animated effects

Test Files

This repository includes sample test files for trying out the raffle functionality:

CSV Test File (src/test/list.csv)

Contains employee data with columns: name, email, department, years_experience

# Test CSV with header and specific column
raffle run "src/test/list.csv" --header --column name --winners 2

# Test CSV selecting from different column  
raffle run "src/test/list.csv" --header --column department --winners 1

# Test CSV with multiple winners and index display
raffle run "src/test/list.csv" --header --column name --winners 3 --show-index

Text Test File (src/test/list.txt)

Contains a simple list of names, one per line

# Test simple text file
raffle run "src/test/list.txt" --winners 1

# Test multiple winners from text file
raffle run "src/test/list.txt" --winners 4

Examples

Example 1: Basic Raffle from CSV

raffle run "C:\data\participants.csv" --header --column "Full Name" --winners 1

Output:

Reading file: C:\data\participants.csv
Processing participants...

Found 50 participants
Detected delimiter: ","

🎉 Selected 1 winner(s):
1. John Smith

Example 2: Multiple Winners from Text File

raffle run "C:\data\names.txt" --winners 3

Output:

Reading file: C:\data\names.txt
Processing participants...

Found 20 participants
Detected delimiter: ","

🎉 Selected 3 winner(s):
1. Alice Johnson
2. Bob Wilson  
3. Carol Davis

Example 3: Department Raffle with Index

raffle run "C:\data\employees.csv" --header --column department --winners 2 --show-index

Output:

Reading file: C:\data\employees.csv
Processing participants...

Found 100 participants
Detected delimiter: ","

🎉 Selected 2 winner(s):
1. [Index] Engineering
2. [Index] Marketing

File Format Support

CSV Files

• Supports any delimiter (comma, semicolon, tab, pipe, etc.)
• Auto-detects delimiter if not specified
• Can have header row with column names
• Can select specific columns for participant extraction

Text Files

• One participant per line
• Simple plain text format
• No delimiter needed

Important Notes

File Paths

• Supports both absolute and relative file paths
• Relative paths are resolved from current working directory
• Examples:
  • ✅ "C:\Users\YourName\Desktop\participants.csv" (absolute)
  • ✅ "/home/user/data/names.txt" (absolute)
  • ✅ "./participants.csv" (relative)
  • ✅ "data/names.txt" (relative)
  • ✅ "src/test/list.csv" (relative)

Security

• Path traversal protection (no .. or ~ allowed)
• Only reads files, never writes or modifies
• Validates file existence before processing

Development

Project Structure

src/
├── cli.ts                    # CLI entrypoint - handles I/O and wires commands
├── commands/                 # Thin command layer - pure functions
│   ├── index.ts             # Command factory exports
│   └── runRaffle.ts         # Main raffle command logic
├── utils/                   # Pure utility functions - no side effects
│   ├── detectDelimiter.ts   # CSV delimiter detection
│   ├── parseFile.ts         # File content parsing
│   ├── format.ts            # Display formatting
│   ├── rng.ts               # Random number generation
│   ├── pickWinners.ts       # Winner selection logic
│   └── io.ts                # I/O helpers (only place allowed to touch fs)
└── test/                    # Test data files
    ├── list.csv             # Sample CSV with employee data
    └── list.txt             # Sample text file with names

Functional Architecture

This project follows functional programming principles:

• No classes - Everything is implemented as pure functions
• Dependency injection - Commands receive utilities as parameters
• Side effects isolation - Only cli.ts and utils/io.ts perform I/O
• Pure functions - All utilities are deterministic and testable
• Immutable data - Functions don't modify input parameters

Available Scripts

# Development
pnpm run dev          # Watch mode for development
pnpm run build        # Compile TypeScript to JavaScript
pnpm run start        # Run the compiled CLI

# Code Quality
pnpm run lint         # Run ESLint on source files
pnpm run lint:fix     # Run ESLint with auto-fix
pnpm run format       # Format code with Prettier
pnpm run format:check # Check code formatting

# Git & Release
pnpm run commit       # Interactive commit with Commitizen
pnpm run release      # Create a new release
pnpm run prepare      # Setup Husky hooks

Contributing

1. Follow the functional programming style
2. Add JSDoc documentation to all functions
3. Write tests for new utilities
4. Use conventional commits
5. Run linting and formatting before committing

License

ISC