> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Serial and form-number helpers

> The two helpers reserved for entity serial IDs and form-numbering formats, with their limited date-token vocabulary.

## When to use these helpers

Use these only in an entity serial configuration or a form-numbering configuration. They are not a general calculated-field API.

## Calling style

Call a helper as `serialPad($sequence, 5)`. In entity-serial and form-numbering editors, autocomplete identifies both helpers as callable functions and shows the signatures below; after `|`, it identifies their transform forms. Not every helper is available everywhere: validation, form, and document-template helpers have distinct context contracts. Editor suggestions are not proof that a helper is supported at runtime.

## Complete function reference

### `serialDate`

Formats a serial date using only yyyy, yy, MM, and dd tokens. An invalid date returns an empty string.

**Signature:** `serialDate(format, value = $now, timezone = $timezone)`

**Example:**

```txt theme={null}
serialDate("yyyy-MM", $now, $timezone) // "2026-07"
```

**Availability:** Entity Serial IDs and form-numbering formats only; both function and transform forms are registered in those contexts.

**Note:** As a transform, the value to the left of the pipe is the date **format**: `"yyyy-MM" | serialDate($now, $timezone)`.

### `serialPad`

Pads a serial sequence from the left. Only the first character of char is used.

**Signature:** `serialPad(value, width, char = "0")`

**Example:**

```txt theme={null}
"CSR-" + serialPad($sequence, 5) // "CSR-00042"
```

**Availability:** Entity Serial IDs and form-numbering formats only; both function and transform forms are registered in those contexts.

**Note:** As a transform, the value to the left of the pipe is the value to pad: `$sequence | serialPad(5)`.

## Runtime behavior and edge cases

### `serialDate` rules

Only `yyyy`, `yy`, `MM`, and `dd` are supported date tokens. Other text and differently cased tokens are literal text; do not expect `YYYY` or time tokens to work like they do in another formatting library. KayanOS converts the input to a date and returns an empty string when it cannot form a valid date. Use the `$timezone` supplied by the serial configuration rather than an unreviewed free-form timezone: the same instant can fall on a different local day at a time boundary.

Use function form when you want the argument order to remain explicit:

```txt theme={null}
serialDate("yyMMdd", $now, $timezone) + "-" + serialPad($sequence, 4)
// Example: "260712-0042"
```

Remember that transform form has a visually different order: the date format, not the date itself, is the value to the left of the pipe. Write `"yyyy-MM" | serialDate($now, $timezone)`, not `$now | serialDate(...)`.

### `serialPad` rules

The helper converts its value to text, so numeric `42` becomes `"42"`. It coerces `width` to a number. A width of zero or less leaves the string unpadded. A width that cannot be converted to a number also leaves the string unpadded. It never truncates a value that is already longer than the requested width. Only the first character of `char` is used; a missing or empty character falls back to `0`. Therefore `serialPad(42, 5, "AB")` returns `"AAA42"`, while `serialPad("123456", 5)` returns `"123456"`.

### What formatting does and does not guarantee

These helpers do not allocate a number, reserve a sequence, or validate uniqueness. They only format the `$sequence` supplied by the serial-issuance path. Keep `$sequence` in the format unless an approved design prevents collisions some other way, and test the expression in preview and in a real issuance flow. Read [Serial IDs](/build/serial-ids) for the context variables, namespace policy, collision behavior, and correction rules.

## Before you publish

* Start with a known value and confirm the expected result.
* Handle null, empty text, and empty lists deliberately.
* Do not place secrets, access tokens, or sensitive personal data in an expression.
* Read [expression contexts and availability](/reference/expressions/contexts) before copying an expression between features.

![Serial and form-number helpers in KayanOS](https://kayanos.app/docs-images/en/reference/expressions-helpers-serial.png)