Strings

string

string: Decoder<string> (source)

Accepts and returns strings.

string.verify(input)

nonEmptyString

nonEmptyString: Decoder<string> (source)

Like string, but will reject the empty string or strings containing only whitespace. Note this is not the same as sized(string, { min: 1 }), which would still accept whitespace-only strings.

nonEmptyString.verify(input)

regex

function regex( pattern: RegExp, message: string ): Decoder<string> (source)

Accepts and returns strings that match the given regular expression.

regex(/^\d{5}$/, 'Must be ZIP code').verify(input)

startsWith

function startsWith( prefix: P ): Decoder<`${P}${string}`> (source)

Available since 2.5.

Accepts and returns strings that start with the given prefix.

startsWith('abc').verify(input)

endsWith

function endsWith( suffix: S ): Decoder<`${string}${S}`> (source)

Available since 2.5.

Accepts and returns strings that end with the given suffix.

endsWith('bar').verify(input)

decimal

decimal: Decoder<string> (source)

Accepts and returns strings with decimal digits only (base-10). To convert these to numbers, use the numeric decoder.

decimal.verify(input)

hexadecimal

hexadecimal: Decoder<string> (source)

Accepts and returns strings with hexadecimal digits only (base-16).

hexadecimal.verify(input)

numeric

numeric: Decoder<number> (source)

Accepts valid numerical strings (in base-10) and returns them as a number. To only accept numerical strings and keep them as string values, use the decimal decoder.

numeric.verify(input)

email

email: Decoder<string> (source)

Accepts and returns strings that are syntactically valid email addresses. (This will not mean that the email address actually exist.)

email.verify(input)

urlString

urlString: Decoder<string> (source)

Available since 2.9.

Accepts strings that are valid URLs, returns the value as a string.

urlString.verify(input)

url

url: Decoder<URL> (source)

Accepts either URL strings or URL instances, returns the value as a URL instance.

url.verify(input)

httpsUrl

httpsUrl: Decoder<URL> (source)

Accepts URL strings and URL instances, but only HTTPS ones. Returns the value as a URL instance.

httpsUrl.verify(input)

Tip! If you need to limit URLs to different protocols than HTTP, you can do as the HTTPS decoder is implemented: by adding further conditions using a .refine() call.

import { url } from 'decoders';

const gitUrl: Decoder<URL> = url.refine(
  (value) => value.protocol === 'git:',
  'Must be a git:// URL',
);

identifier

identifier: Decoder<string> (source)

Available since 2.4.

Accepts and returns strings that are valid identifiers in most programming languages.

identifier.verify(input)

nanoid

function nanoid( { size: number } ): Decoder<string> (source)

function nanoid( { min?: number; max?: number } ): Decoder<string> (source)

Available since 2.4.

Accepts and returns Nano ID string values. By default, expects a standard 21-char nanoid, but you can optionally specify different size constraints. It assumes the default nanoid alphabet. If you're using a custom alphabet, use regex() instead.

nanoid().verify(input)

uuid

uuid: Decoder<string> (source)

Accepts strings that are valid UUIDs (universally unique identifier).

uuid.verify(input)

uuidv1

uuidv1: Decoder<string> (source)

Like uuid, but only accepts UUIDv1 strings.

uuidv1.verify(input)

uuidv4

uuidv4: Decoder<string> (source)

Like uuid, but only accepts UUIDv4 strings.

uuidv4.verify(input)

Limiting string size

function sized( decoder: Decoder<string>, limit: { size: number } ): Decoder<string> (source)

function sized( decoder: Decoder<string>, limit: { min?: number; max?: number } ): Decoder<string> (source)

Available since 2.9.

Takes any string decoder and rejects values that don't match the given size constraints. Also works with arrays and sets.

SizeOptions accepts min, max, or size (shorthand for exact length).

sized(string, { min: 2, max: 10 }).verify(input)