Skip to content

Add toHuman: describe a cron expression in English#4

Merged
merencia merged 1 commit into
masterfrom
reverse-readback
Jun 22, 2026
Merged

Add toHuman: describe a cron expression in English#4
merencia merged 1 commit into
masterfrom
reverse-readback

Conversation

@merencia

Copy link
Copy Markdown
Member

Adds the reverse direction: toHuman(cron) turns a 5- or 6-field node-cron expression back into plain English. It's the readback for a toCron call ("you wrote X, here's the cron, which reads as Y").

What it does

import { toHuman } from 'cron-translate';

toHuman('0 0 9 * * *');     // "at 9am"
toHuman('0 0 18 * * 1-5');  // "at 6pm on monday to friday"
toHuman('0 */5 9 * * *');   // "every 5 minutes at 9am"
toHuman('0 0 0 * * 5L');    // "last friday of the month"

Covers frequency, clock times, field values/lists/ranges, ordinals (L/#), and accepts month/weekday names in the input (MON-FRI, JAN).

Round-trip property

The English is phrased so that toCron parses it back to the same expression:

toCron(toHuman(cron)) === cron

This is the round-trip oracle from the design: the readback reuses the toCron grammar rather than reinventing a cron describer, and the test suite asserts the property over every cron the forward direction can produce.

Scope

The readback prioritizes correctness and round-trip fidelity over perfect prose. English-only (no i18n). Rare composite shapes (e.g. a wildcard seconds field combined with a specific time) may not get the prettiest phrasing, though the round-trip holds for everything the forward parser generates.

Checks

  • npm run typecheck, npm run lint, npm run build: clean.
  • npm test: 142 tests (67 forward + 75 reverse), all green. test/to-human.test.ts round-trips every forward golden cron plus explicit readability assertions.

Reverse direction (readback) of toCron. Parses a 5- or 6-field node-cron
expression and renders a readable English sentence phrased so that toCron parses
it back to the same expression: toCron(toHuman(cron)) === cron.

- frequency (every minute, every 5 minutes, every hour)
- clock times (at 9am, at 2:30pm, at noon, at midnight)
- field values/lists/ranges (at minute 0, 15, 30 and 45; between 9am and 5pm)
- ordinals (last friday of the month, first monday of the month, last day)
- month/weekday names accepted in input (MON-FRI, JAN)

Adds test/to-human.test.ts: round-trip oracle over every forward golden cron,
plus explicit readability assertions (75 cases). Documents toHuman in README.
@merencia merencia merged commit 45894dc into master Jun 22, 2026
3 checks passed
@merencia merencia deleted the reverse-readback branch June 22, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant