# @checkly/handlebars

Checkly's Handlebars wrapper. It exposes a Handlebars instance plus `create()`, with a
curated set of helpers:

- **Custom:** `$RANDOM_NUMBER`, `$UUID`, `split`, `tagValue`, `startsWith`, `replace`
- **Comparison:** `and`, `or`, `not`, `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `compare`,
  `contains`, `has`, `is`, `isnt`, `ifEq`, `ifEven`, `ifOdd`, `ifNth`, `unlessEq`, … (the
  full `comparison` category)
- **Date:** `year`, `date`, `moment`

```js
const Handlebars = require('@checkly/handlebars')
Handlebars.create().compile('Bearer {{TOKEN}}')({ TOKEN: 'secret' }) // 'Bearer secret'
```

```js
Handlebars.create().compile('{{tagValue TAGS "applicationname" "UNKNOWN"}}')({
  TAGS: ['team:platform', 'applicationname:api'],
}) // 'api'
```

## Date helpers

`{{moment}}` and `{{date}}` are the same helper, backed by dayjs (moment-compatible
format tokens like `YYYY-MM-DD`, plus the `X`/`x` unix tokens):

- `{{moment}}` — now, default long format (`June 22, 2026`)
- `{{moment "YYYY-MM-DD"}}` — format now with the given pattern
- `{{moment "<input>" "<fmt>"}}` — parse the input, format it with the pattern

The input is an absolute date (anything dayjs parses, e.g. `2020-06-15`) or one of these
relative phrases:

```
now | today | yesterday | tomorrow
<count> <unit>[s] ago              e.g. "2 days ago", "an hour ago"
[in] <count> <unit>[s] [from now]  e.g. "in a month", "3 weeks", "1 year from now"
last|next <unit>                   e.g. "next month"
<count> := a number | a | an
<unit>  := second|minute|hour|day|week|month|year
```

Anything else throws an error naming the input, so templating fails loudly instead of
silently rendering the literal `Invalid Date`.

## Development

TypeScript, built with `tsc` to `dist/` (CJS + `.d.ts`); Biome for lint/format; Vitest
for tests. All runtime deps are pinned to exact versions.

```sh
pnpm build       # tsc -> dist
pnpm test        # vitest (locks in helper behaviour — comparison/date/custom)
pnpm lint        # biome
pnpm typecheck   # tsc --noEmit
```