String Format Guards

Runtime type guards to check different string formats.

Import

import {
  isEmail, isEmailArray, isURL, isPhoneNumber, isIPAddress,
  isUUID, isBase64, isHexString, isBinaryString
} from 'toolbox-x/guards';

isEmail

Validates if a string conforms to standard email format.

Signature

isEmail(value: unknown): value is string

Description

Uses comprehensive regex pattern covering:

Local part (before @)
Domain part (after @)
Top-level domain (2+ characters)
Common special characters (., %, +, -)

Examples

playground.ts

isEmailArray

Validates that all elements in an array are valid email strings. Combines array and email validation in single operation.

Signature

isEmailArray(value: unknown): value is string[]

Examples

playground.ts

// Practical usage
function processContacts(emails: unknown) {
  if (isEmailArray(emails)) {
    return emails.map(sendNewsletter); // emails is string[]
  }
  throw new Error('Invalid email list');
}

isUUID

Validates if a value is a string representing a UUID of version 1–8 (RFC4122).

Signature

isUUID(value: unknown): value is UUID<UUIDVersion>

Description

It checks:

8-4-4-4-12 hexadecimal digit pattern.
Version marker in the third group (1-8).
Variant marker in the fourth group (8, 9, a, or b).

Info

It checks uuid in case-insensitive mode.
It narrows down the value to a branded type UUID<UUIDVersion> where UUIDVersion is the UUID version (v1–v8).

Examples

playground.ts

// Practical usage
interface Resource {
  id: UUID<UUIDVersion>;
  name: string;
}

function validateResource(res: unknown): res is Resource {
  return isObject(res) && isUUID(res.id) && isString(res.name);
}

Type Definitions

/** UUID versions as string from `v1-v8` */
type UUIDVersion = `v1` | `v2` | `v3` | `v4` | `v5` | `v6` | `v7` | `v8`;

/** General 5 parts UUID string type */
type $UUID = `${string}-${string}-${string}-${string}-${string}`;

/** General 5 parts UUID string as branded type */
type UUID<V extends UUIDVersion> = Branded<$UUID, V>;

Notes

Supports UUID versions 1–8.
Returns a branded type to help enforce version-specific UUID typing in TypeScript.
Case-insensitive validation.

isURL

Validates if a string is a properly formatted URL using the browser's URL constructor.

Signature

isURL(value: unknown): value is string

Description

It checks:

Valid protocol (http/https/ftp etc.)
Proper domain structure
Optional path/query/hash components

Info

This guard uses the JavaScript's URL constructor to validate the URL.
If the URL constructor throws an error, the guard returns false.

Examples

playground.ts

// Safe URL creation
function createLink(href: unknown) {
  return isURL(href) ? new URL(href) : null;
}

isBase64

Validates if a string is properly Base64 encoded. Accepts both standard and URL-safe variants including padding.

Signature

isBase64(value: unknown): value is string

Examples

playground.ts

// Decoding safely
function decodeBase64(input: unknown) {
  return isBase64(input) ? atob(input) : null;
}

isHexString

Validates if a string is a valid hexadecimal byte sequence. Accepts both spaced and un-spaced formats, with flexible whitespace between bytes.

Signature

isHexString(value: unknown): value is string

Examples

playground.ts

// Safe conversion
function hexToBytes(input: unknown) {
  return isHexString(input) 
    ? Buffer.from(input.replace(/\s+/g, ''), 'hex') 
    : null;
}

isBinaryString

Validates if a string is a valid binary byte sequence. Accepts both spaced and un-spaced formats, with flexible whitespace between bytes. Each byte must consist of exactly 8 bits.

Signature

isBinaryString(value: unknown): value is string

Examples

playground.ts

// Safe processing
function binaryToDecimal(input: unknown) {
  return isBinaryString(input) 
    ? parseInt(input.replace(/\s+/g, ''), 2) 
    : null;
}

isPhoneNumber

Validates international phone numbers using E.164 format standard.

Signature

isPhoneNumber(value: unknown): value is string

Description

It checks:

Optional leading +
Country code (1-15 digits)
Subscriber number

Examples

playground.ts

// Formatting example
function formatPhone(input: unknown) {
  if (isPhoneNumber(input)) {
    return input.startsWith('+') ? input : `+${input}`;
  }
  return null;
}

isIPAddress

Validates IP addresses.

Signature

isIPAddress(value: unknown): value is string

Description

Validates both IPv4 and IPv6 address formats including:

IPv4 dotted notation (192.168.1.1)
IPv6 hexadecimal notation (2001:0db8:85a3::8a2e:0370:7334)
Compressed IPv6 forms
Does NOT validate range/scope

Examples

playground.ts

// Usage
function blockIP(ip: unknown) {
  if (isIPAddress(ip)) {
    firewall.addBlock(ip);  // ip is string
  }
}

isJSON

Validates if a string contains valid JSON. More strict than isString as it verifies parsable content.

Signature

isJSON(value: unknown): value is string

Examples

playground.ts

// Practical usage
function parseIfJSON(input: unknown) {
  if (isJSON(input)) {
    return JSON.parse(input);
  }
  return input;
}

Notes

Only returns true for strings that can be parsed
Rejects JSON fragments (must be valid top-level value)
Useful for API response validation

Aliases

Main Export	Alias Names
`isJSON`	`isValidJSON`
`isURL`	`isValidURL`
`isEmail`	`isValidEmail`

On this page