Team Scheduler CLI

A TypeScript CLI application for building schedules for teams that work on Sundays and Wednesdays only.

Features

• ✅ Only schedules on Sundays and Wednesdays
• ✅ Assigns only one member per event
• ✅ Ensures fair distribution of assignments
• ✅ Handles member unavailability dates
• ✅ Supports custom date ranges
• ✅ JSON input/output support
• ✅ Built-in validation

Installation

cd scheduler
npm install
npm run build

Usage

Basic Usage (with example data)

npm start

Using Custom Team Data

npm start -m team.json -s 2025-07-01 -e 2025-12-31

Generate Sample File

npm start generate-sample

Save Schedule to File

npm start -o schedule.json

CLI Options

• -m, --members <file>: JSON file containing team members and unavailable dates
• -s, --start <date>: Start date (YYYY-MM-DD) [default: today]
• -e, --end <date>: End date (YYYY-MM-DD) [default: 3 months from today]
• -o, --output <file>: Output file for the schedule (optional)
• -h, --help: Show help message

Team Data Format

The team members file should be in JSON format:

{
  "members": [
    {
      "id": "1",
      "name": "Alice Johnson",
      "unavailableDates": [
        "2025-06-15",
        "2025-06-29",
        "2025-07-13"
      ]
    },
    {
      "id": "2",
      "name": "Bob Smith",
      "unavailableDates": [
        "2025-06-18",
        "2025-07-02",
        "2025-07-16"
      ]
    }
  ]
}

Output Format

The schedule output includes:

1. Schedule List: Date, day of week, and assigned member
2. Assignment Statistics: Number of assignments per member
3. Fairness Check: Validation that no member has significantly more assignments

Example Output

=== TEAM SCHEDULE ===
Period: 2025-07-01 to 2025-08-01
Total events: 9

2025-07-03 (Wednesday): Alice Johnson
2025-07-07 (Sunday): Bob Smith
2025-07-10 (Wednesday): Carol Williams
...

=== ASSIGNMENT STATISTICS ===
Alice Johnson: 3 assignment(s)
Bob Smith: 2 assignment(s)
Carol Williams: 2 assignment(s)
David Brown: 2 assignment(s)

✓ Schedule is fair - no member has significantly more assignments than others

How It Works

1. Date Filtering: Only considers Sundays (day 0) and Wednesdays (day 3)
2. Availability Check: Excludes members who are unavailable on specific dates
3. Fair Assignment: Uses a round-robin approach, always selecting the member with the fewest current assignments
4. Validation: Ensures the final schedule is fair (max difference of 1 assignment between any two members)

Requirements Met

• ✅ Sunday/Wednesday Only: Only schedules events on these days
• ✅ One Member per Event: Each event has exactly one assigned member
• ✅ Fair Distribution: No member gets the majority of assignments
• ✅ Unavailability Handling: Respects member unavailable dates
• ✅ TypeScript CLI: Built as a command-line application in TypeScript

Project Structure

scheduler
├── src
│   ├── index.ts          # Entry point of the CLI application
│   ├── scheduler.ts      # Contains the Scheduler class for building schedules
│   ├── types
│   │   └── index.ts      # Defines interfaces for Members, Schedule, and Availability
│   ├── utils
│   │   └── validation.ts  # Utility functions for validating input data
│   └── models
│       ├── team.ts       # Manages team members and their unavailable dates
│       └── schedule.ts    # Represents the schedule and manages events
├── package.json           # npm configuration file
├── tsconfig.json          # TypeScript configuration file
└── README.md              # Documentation for the project

Installation

1. Clone the repository:

   git clone <repository-url>
   cd scheduler
   

2. Install the dependencies:

   npm install
   

Usage

To run the application, use the following command:

npm start -- <command-line-arguments>

Replace <command-line-arguments> with the necessary parameters to specify team members and their availability.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

License

This project is licensed under the MIT License.