dsh-when

In Chinese-language agent workflows, users naturally say things like "tomorrow 9am" or "2 hours later", while downstream schedulers and reminder services demand a precise ISO 8601 timestamp. Manual conversion is tedious and error-prone across time zones and daylight-saving edges. dsh-when fills that gap: it registers a lightweight when tool that turns a Chinese relative-time phrase into a UTC ISO string, a local ISO string with offset, a relative-seconds delta, and the matched pattern name—all in pure ESM with zero dependencies and no build step.

The parser covers five phrase families: day offsets (today, tomorrow, day-after, optionally with a clock time), durations (N minutes, hours, days, or weeks from now), weekday expressions (next week X, auto-rolling forward when this week has passed), bare clock times (HH:MM, rolling to next day if already past), and raw ISO 8601 input. Every input follows a strict fail-fast principle: phrases outside the supported table return ok:false with a complete list of accepted forms, so a vague phrase can never silently produce a wrong timestamp and propagate into a scheduler or log.

It pairs naturally with dsh-cron-parse (periodic cron expressions) and dsh-scheduler (one-shot triggers): cron handles recurring schedules while when handles one-off moments, and the ISO output flows straight into the same scheduling pipeline. If you are building Chinese-facing agents for reminders, scheduling, or timestamped logging, dsh-when is a drop-in, zero-dependency choice.