Skip to content

Is postal code

isPostalCode validates that a value is an alphanumeric postal code.

It enforces a flexible but bounded pattern: the value must be a string containing only letters, digits, spaces, or hyphens, and must be between 3 and 12 characters long. This supports a wide range of international postal formats while preventing malformed or trivially invalid codes. Any non‑string value or string that fails the pattern results in a single validation event. Otherwise, it produces no validation output.

Signature

Through the API:

.isPostalCode();

And internally:

export const isPostalCode: ValidationRule
(value: unknown, path: FieldPath) => Promise<ReadonlyArray<JaneEvent>>

Events

Event code Description
type.not.valid Value is not a string.
string.not.postal-code String does not match the postal‑code pattern.

Design rationale

  • Supports a broad set of international postal formats without country‑specific assumptions.
  • Rejects non‑string values early with a structural‑type diagnostic.
  • Accepts letters, digits, spaces, and hyphens — common across global postal systems.
  • Enforces a reasonable length range (3–12) to avoid trivially invalid codes.
  • Emits exactly one event per failure for clarity and composability.
  • Pure, total, async‑compatible, and returns a readonly array of JaneEvent objects.
  • Preserves the provided path and supports pipeline‑level userMessage overrides.

Invoke

isPostalCode runs only when explicitly included in a boundary or pipeline. It does not run automatically.

The rule activates when:

  • The value is any JavaScript value.
  • If the value is not a string, emits type.not.valid.
  • If the string does not match /^[A-Za-z0-9 \\-]{3,12}$/, emits string.not.postal-code.
  • Otherwise, returns an empty result set.

Examples

Valid — common postal formats

await isPostalCode("90210", "$");
// → []

await isPostalCode("SW1A 1AA", "$");
// → []

await isPostalCode("K1A-0B1", "$");
// → []

Invalid — non‑string values

await isPostalCode(12345, "$");
// → [
//     JaneEvent{
//       kind: "error",
//       code: "type.not.valid",
//       path: "$",
//       ...
//     }
//   ]

Invalid — incorrect format or length

await isPostalCode("A!", "$");
// → [
//     JaneEvent{
//       kind: "error",
//       code: "string.not.postal-code",
//       path: "$",
//       ...
//     }
//   ]

await isPostalCode("TOO-LONG-POSTAL-CODE", "$");
// → [
//     JaneEvent{
//       kind: "error",
//       code: "string.not.postal-code",
//       path: "$",
//       ...
//     }
//   ]