Strings

string

string: Decoder<string> (source)

Accepts and returns strings.

// 👍
string.verify('hello world') === 'hello world';
string.verify('🚀') === '🚀';
string.verify('') === '';

// 👎
string.verify(123); // throws
string.verify(true); // throws
string.verify(null); // throws

nonEmptyString

nonEmptyString: Decoder<string> (source)

Like string, but will reject the empty string or strings containing only whitespace.

// 👍
nonEmptyString.verify('hello world') === 'hello world';
nonEmptyString.verify('🚀') === '🚀';

// 👎
nonEmptyString.verify(123); // throws
nonEmptyString.verify('  '); // throws
nonEmptyString.verify(''); // throws

regex

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

Accepts and returns strings that match the given regular expression.

const decoder = regex(/^[0-9][0-9]+$/, 'Must be numeric');

// 👍
decoder.verify('42') === '42';
decoder.verify('83401648364738') === '83401648364738';

// 👎
decoder.verify(''); // throws
decoder.verify('1'); // throws
decoder.verify('foo'); // throws

startsWith

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

Accepts and returns strings that start with the given prefix.

const decoder = startsWith('abc');

// 👍
decoder.verify('abc') === 'abc';
decoder.verify('abcdefg') === 'abcdefg';

// 👎
decoder.verify(42); // throws
decoder.verify('ab'); // throws
decoder.verify('ABC'); // throws

endsWith

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

Accepts and returns strings that end with the given suffix.

const decoder = endsWith('bar');

// 👍
decoder.verify('bar') === 'bar';
decoder.verify('foobar') === 'foobar';

// 👎
decoder.verify(42); // throws
decoder.verify('Bar'); // throws
decoder.verify('bark'); // throws

decimal

decimal: Decoder<string> (source)

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

const decoder = decimal;

// 👍
decoder.verify('42') === '42';
decoder.verify('83401648364738') === '83401648364738';

// 👎
decoder.verify(''); // throws
decoder.verify('123abc'); // throws
decoder.verify('foo'); // throws
decoder.verify(123); // throws (not a string)

hexadecimal

hexadecimal: Decoder<string> (source)

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

const decoder = hexadecimal;

// 👍
decoder.verify('0123456789ABCDEF') === '0123456789ABCDEF';
decoder.verify('deadbeef') === 'deadbeef';

// 👎
decoder.verify('abcdefghijklm'); // throws (not hexadecimal)
decoder.verify(''); // throws
decoder.verify('1'); // throws

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.

const decoder = numeric;

// 👍
decoder.verify('42') === 42;
decoder.verify('83401648364738') === 83401648364738;

// 👎
decoder.verify(''); // throws
decoder.verify('123abc'); // throws
decoder.verify('foo'); // throws
decoder.verify(123); // throws (not a string)

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('alice@acme.org') === 'alice@acme.org';

// 👎
email.verify('foo'); // throws
email.verify('@acme.org'); // throws
email.verify('alice @ acme.org'); // throws

url

url: Decoder<URL> (source)

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

// 👍
url.verify('http://nvie.com') === new URL('http://nvie.com/');
url.verify('https://nvie.com') === new URL('https://nvie.com/');
url.verify('git+ssh://user@github.com/foo/bar.git') ===
  new URL('git+ssh://user@github.com/foo/bar.git');

// 👎
url.verify('foo'); // throws
url.verify('@acme.org'); // throws
url.verify('alice @ acme.org'); // throws
url.verify('/search?q=foo'); // throws

httpsUrl

httpsUrl: Decoder<URL> (source)

Accepts strings that are valid URLs, but only HTTPS ones. Returns the value as a URL instance.

// 👍
httpsUrl.verify('https://nvie.com:443') === new URL('https://nvie.com/');

// 👎
httpsUrl.verify('http://nvie.com'); // throws, not HTTPS
httpsUrl.verify('git+ssh://user@github.com/foo/bar.git'); // throws, not HTTPS

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)

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

// 👍
identifier.verify('x') === 'x';
identifier.verify('abc123') === 'abc123';
identifier.verify('_123') === '_123';
identifier.verify('a_b_c_1_2_3') === 'a_b_c_1_2_3';

// 👎
identifier.verify('123xyz'); // cannot start with digit
identifier.verify('x-y'); // invalid chars
identifier.verify('!@#$%^&*()=+'); // invalid chars
identifier.verify('🤯'); // invalid chars
identifier.verify(42); // not a string

nanoid

nanoid: Decoder<string> (source)

Accepts and returns nanoid string values. It assumes the default nanoid alphabet. If you're using a custom alphabet, use regex() instead.

// 👍
nanoid().verify('1-QskICa3CaPGcKuYYTm1') === '1-QskICa3CaPGcKuYYTm1';
nanoid().verify('vA4mt7CUWnouU6jTGbMP_') === 'vA4mt7CUWnouU6jTGbMP_';
nanoid({ size: 7 }).verify('yH8mx-7') === 'yH8mx-7';
nanoid({ min: 7, max: 10 }).verify('yH8mx-7') === 'yH8mx-7';
nanoid({ min: 7, max: 10 }).verify('yH8mx-7890') === 'yH8mx-7890';

// 👎
nanoid().verify('123E4567E89B12D3A456426614174000'); // too long
nanoid().verify('abcdefghijkl'); // too short
nanoid().verify('$*&(#%*&('); // invalid chars

uuid

uuid: Decoder<string> (source)

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

// 👍
uuid.verify('123e4567-e89b-12d3-a456-426614174000') ===
  '123e4567-e89b-12d3-a456-426614174000';
uuid.verify('123E4567-E89B-12D3-A456-426614174000') ===
  '123E4567-E89B-12D3-A456-426614174000';

// 👎
uuid.verify('123E4567E89B12D3A456426614174000'); // throws
uuid.verify('abcdefgh-ijkl-mnop-qrst-uvwxyz012345'); // throws

uuidv1

uuidv1: Decoder<string> (source)

Like uuid, but only accepts UUIDv1 strings.

// 👍
uuidv1.verify('123e4567-e89b-12d3-a456-426614174000') ===
  '123e4567-e89b-42d3-a456-426614174000';

// 👎
uuidv1.verify('123e4567-e89b-42d3-a456-426614174000'); // throws

uuidv4

uuidv4: Decoder<string> (source)

Like uuid, but only accepts UUIDv4 strings.

// 👍
uuidv4.verify('123e4567-e89b-42d3-a456-426614174000') ===
  '123e4567-e89b-42d3-a456-426614174000';

// 👎
uuidv4.verify('123e4567-e89b-12d3-a456-426614174000'); // throws

On this page