This package allows you to quickly calculate time expressions like "1h + 30m" and get human-readable results.

✅ Works as:

• Alfred Workflow (tc 1h + 30m)
• CLI tool (tc "1h + 30m")
• Node.js module (import { calculate } from "alfred-time-calculator")

🏆 Featured in Amazing Alfred Workflows

1. Download the Workflow
2. Open Alfred → Preferences → Workflows
3. Drag & drop the workflow
4. Use the keyword tc in Alfred:
   • Example: tc 2h + 45m
   • Output: "2 hours, 45 minutes"

You can install the package globally and use it in the terminal:

npm install -g alfred-time-calculator

Now you can run:

tc "1h + 30m"

Output:

1 hour, 30 minutes

Install the package:

npm install alfred-time-calculator

Then import and use in your project:

import { calculate } from "alfred-time-calculator";

console.log(calculate("2h - 10s"));
// Output: "1 hour, 59 minutes, 50 seconds"

• Convert expressions like 1h + 30m - 5s / 2
• Supports days, hours, minutes, seconds, milliseconds
• Supports at <date> → returns relative duration (in 3 days, 2 months ago)
• Supports in <duration>, <duration> ago → returns absolute date
• Supports weekdays: in 5 weekdays, 3 weekdays ago
• Handles ultra ancient / future dates: ~25475 BC, ~12000 AD
• CLI support (tc command)
• Multiplication and division: 2d * 3, 1h / 2
• Formatted output: "1 hour, 30 minutes"
• Alfred support via Script Filter

• d – days
• w – weeks
• h – hours
• m – minutes
• s – seconds
• ms – milliseconds

You can combine expressions (1h + 30m - 5s / 2) and use multiplication/division (2d * 3, 1h / 2).

When installed globally, this package registers the tc command as a CLI tool.

It is defined in package.json under bin:

{
  "bin": {
    "tc": "./dist/cli.js"
  }
}

This allows you to use tc in any terminal after installing the package globally.

To test it locally before publishing, use:

npm link

This will make tc available without installing from NPM.

To remove the local link:

npm unlink -g alfred-time-calculator

This tool also understands natural language date expressions and returns relative durations or absolute dates.

⚠️ Note:

• Avoid using only a year (like tc at 2020) — use a full date or add a month (e.g. tc at jan 2020)
• Dates like "tc at last sunday" assume noon (12:00) by default if no time is specified.

⚠️ Note on weekdays:

• weekday(s) means working days from Monday to Friday
• Public holidays are not taken into account, as they vary by country

You can calculate the duration between two dates or times using natural expressions:

from <date or time> to <date or time>
between <date or time> and <date or time>
from <date or time> until <date or time>
from <date or time> till <date or time>

Example: from monday to friday, from 10:00 until 18:30, from yesterday to next sunday

⚠️ Notes:

• If either date is missing or can't be parsed, no result will be returned
• You can compare past, present, or future dates and times

• Parses time units like 1h, 30m, 5s using the ms module
• Evaluates expressions like 1h + 30m - 5s / 2 by replacing time units with seconds and computing the result using a secure math expression parser (expr-eval).
• Formats durations like "2 hours, 45 minutes" using date-fns
• Calculates time deltas (at, in, ago) via date-fns
• Parses natural language dates using chrono-node
  • Supports expressions like "next Friday", "2 weeks ago", "tomorrow at 10pm", "Jan 2000"
• Formats dates using Intl.DateTimeFormat in the user's local timezone
• Returns Alfred-compatible JSON via the Script Filter

To build the project:

pnpm run build:workflow   # Build Alfred workflow bundle
pnpm run build:node       # Build Node.js CLI and library

To run tests:

pnpm test

• Created by Shura Vlasov, with little help from Chat GPT 🤖
• GitHub: github.com/shura-v

🚀 Now you can calculate time expressions in Alfred, terminal, and Node.js!