📋 Table of Contents

• Features
• Installation
• Usage
• Time Units
• Modes
• Examples
• Output Formats
• Contributing
• License

✨ Features

• Simple & Intuitive: Natural time expressions like 5d, 17h, 0.5d
• Multiple Modes: Calculate past times (default), future times, or use math expressions
• Flexible Units: Support for seconds, minutes, hours, days, weeks, months, years, and quarters
• Constant Flags: Quick shortcuts like lm (last month), nw (next week)
• Smart Formatting: Automatically formats output based on time range
• Math Mode: Perform complex calculations with + and - operators
• Error Handling: Helpful error messages and suggestions

📦 Installation

Global Installation (Recommended)

npm install -g @jhauga/timecal

Local Installation

npm install @jhauga/timecal

Quick Start (npx)

npx @jhauga/timecal 5d

🚀 Usage

Basic Syntax

timecal [options] <time_expression>

Options

| Option | Description | |--------|-------------| | -h, --help | Display help information | | -f, --future | Calculate time in the future | | -p, --past | Calculate time in the past (default) | | -m, --math | Use mathematical expressions with + and - operators |

⏱️ Time Units

| Unit | Description | Example | |------|-------------|---------| | s | Seconds | 30s = 30 seconds | | m | Minutes | 45m = 45 minutes | | h | Hours | 5h = 5 hours | | d | Days | 7d = 7 days | | w | Weeks | 2w = 2 weeks | | M | Months | 3M = 3 months | | y | Years | 1y = 1 year | | q | Quarters | 2q = 2 quarters (6 months) |

Decimal Values

You can use decimal values for more precision:

timecal 0.5d   # Half a day (12 hours)
timecal 1.5h   # One and a half hours
timecal 2.25d  # 2 days and 6 hours

🎯 Modes

Past Mode (Default)

Calculate times in the past. No flag required, or use -p / --past.

timecal 5d        # 5 days ago
timecal -p 17h    # 17 hours ago

Future Mode

Calculate times in the future using -f or --future.

timecal -f 5d     # 5 days from now
timecal --future 2w   # 2 weeks from now

Math Mode

Perform complex calculations with + and - operators using -m or --math.

timecal -m +17h + 9m      # 17 hours and 9 minutes in the future
timecal -m -20h - 2d      # 20 hours and 2 days in the past
timecal -m +3d + 5h - 2m  # Complex calculation

Shortcut: You can omit the -m flag if your expression starts with + or -:

timecal +17h     # Math mode implied (17 hours in the future)
timecal -5d      # Math mode implied (5 days in the past)

🏷️ Constant Flags

Quick shortcuts for common time references:

Past Flags

| Flag | Description | Equivalent | |------|-------------|------------| | lm | Last month | 1M in past mode | | lw | Last week | 1w in past mode | | ly | Last year | 1y in past mode | | lq | Last quarter | 1q in past mode |

Future Flags

| Flag | Description | Equivalent | |------|-------------|------------| | nm | Next month | 1M in future mode | | nw | Next week | 1w in future mode | | ny | Next year | 1y in future mode | | nq | Next quarter | 1q in future mode |

Smart Error Checking: If you use a future flag in past mode (or vice versa), TimeCal will suggest the correct flag:

timecal lm        # ✓ Correct
timecal nm        # ✗ Error: Invalid past flag "nm". Did you mean "lm"?
timecal -f lm     # ✗ Error: Invalid future flag "lm". Did you mean "nm"?

📝 Examples

Simple Past Calculations

timecal 17h
# Output: 1:10 AM

timecal 5d
# Output: 02-22-2026 Saturday

timecal lm
# Output: 01-27-2026 Tuesday

Simple Future Calculations

timecal -f 17h
# Output: 7:34 PM

timecal --future 5d
# Output: 03-04-2026 Wednesday

timecal --future nm
# Output: 03-27-2026 Friday

Multiple Time Units

timecal 0.5d 83m
# Output: 10:04 PM

timecal 15M 200h
# Output: 11-11-2025 Tuesday 10:34 AM

timecal -f 2d 3h 15m
# Output: 03-01-2026 Sunday 9:49 PM

Math Mode

timecal -m +17h + 9m + 1h
# Output: 3:43 PM

timecal -m -17h - 9m - 1h
# Output: 11:25 AM

timecal -m +20h + 2d
# Output: 03-01-2026 Sunday 2:34 PM

timecal -m -20h - 2M
# Output: 12-27-2025 Saturday 10:34 AM

Implicit Math Mode

timecal +17h
# Output: 1:34 PM (17 hours from now)

timecal -5d
# Output: 02-22-2026 Saturday (5 days ago)

timecal +3d -2h
# Output: 03-02-2026 Monday 4:34 PM

📄 Output Formats

TimeCal automatically formats output based on the time range:

Less than 24 Hours

Shows time only in 12-hour format:

1:10 AM
11:34 PM
6:45 PM

24 Hours or More (with time units)

Shows date, day of week, and time:

02-27-2026 Thursday 1:10 AM
12-26-2025 Friday 11:34 PM
01-05-2026 Monday 6:45 PM

24 Hours or More (without time units)

Shows date and day of week only:

02-27-2026 Thursday
12-26-2025 Friday
01-05-2026 Monday

Format Pattern: MM-DD-YYYY DayName HH:MM AM/PM

🧪 Testing Your Installation

After installation, test with these commands:

# Should show time 5 hours ago
timecal 5h

# Should show date 1 week from now
timecal -f 1w

# Should show help
timecal --help

🛠️ Development

Clone the Repository

git clone https://github.com/jhauga/timeCal.git
cd timeCal

Install Dependencies

npm install

Link for Local Testing

npm link

Now you can use timecal command globally for testing.

📚 API

While TimeCal is primarily a CLI tool, you can also use its modules programmatically:

const { parseArguments } = require('@jhauga/timecal/lib/parser');
const { calculate } = require('@jhauga/timecal/lib/calculator');
const { formatOutput } = require('@jhauga/timecal/lib/formatter');

const args = ['5d', '3h'];
const parsed = parseArguments(args);
const result = calculate(parsed);
const output = formatOutput(result);

console.log(output);

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

🐛 Issues

Found a bug or have a feature request? Please open an issue.

📄 License

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

👤 Author

jhauga

• GitHub: @jhauga
• Package: @jhauga/timecal

🌟 Show Your Support

Give a ⭐️ if this project helped you!

📈 Roadmap

• [ ] Add support for custom date formats
• [ ] Add timezone support
• [ ] Add more constant flags (yesterday, tomorrow, etc.)
• [ ] Add support for specific dates as reference points
• [ ] Add color output option
• [ ] Add JSON output format option