Skip to content

Parsers Reference

Coverage License NPM Version Open Issues Size

πŸ‘οΈβ€πŸ—¨οΈ Parsers without nonsense.

Instead of throwing or returning values like NaN, the parsers in this library either return the expected parsed value or undefined (making use of the Maybe type).

Usage

πŸ“¦ Node

Install @lou.codes/parsers as a dependency:

Terminal window
pnpm add @lou.codes/parsers
# or
npm install @lou.codes/parsers
# or
yarn add @lou.codes/parsers

Import it and use it:

import { parseDecimal } from "@lou.codes/parsers";
parseDecimal("101"); // 101
parseDecimal("nope"); // undefined

πŸ¦• Deno

Import @lou.codes/parsers using the npm: prefix, and use it directly:

import { parseDecimal } from "npm:@lou.codes/parsers";
parseDecimal("101"); // 101
parseDecimal("nope"); // undefined

🌎 Browser

Import @lou.codes/parsers using esm.sh, and use it directly:

<script type="module">
import { parseDecimal } from "https://esm.sh/@lou.codes/parsers";
parseDecimal("101"); // 101
parseDecimal("nope"); // undefined
</script>

Common

attempt

β–Έ attempt<Arguments, Output>(wrappedFunction): (…parameters: Arguments) => Maybe<Output>

Wrapper for try/catch.

Type parameters

NameTypeDescription
Argumentsextends ReadOnlyArrayType of the arguments of the function to be wrapped.
OutputOutput-

Parameters

NameTypeDescription
wrappedFunctionFunction<Arguments, Output>Function to be wrapped.

Returns

fn

Function wrapped in try/catch.

β–Έ (...parameters): Maybe<Output>

Parameters
NameType
...parametersArguments
Returns

Maybe<Output>

Remarks

This functions tries to run a function and silences the throws by wrapping it with a try/catch and returning undefined instead.

Example

const willFail = () => {
throw new Error("fail");
};
const safeWillFail = attempt(willFail);
safeWillFail(); // undefined

View source


clone

β–Έ clone<Type>(value): Maybe<Type>

Safely clones a value, returning undefined if any part of the input value is not serializable.

Type parameters

NameDescription
TypeType of the value to be cloned.

Parameters

NameTypeDescription
valueTypeValue to be cloned.

Returns

Maybe<Type>

Clone of the value or undefined if can’t be serialized.

Remarks

This util makes use of structuredClone to clone the given value, but instead of throwing a DataCloneError, it simply returns undefined when the value is not serializable.

Example

clone({ foo: "bar" }); // { foo: "bar" }
clone({ function: () => {} }); // undefined

See

View source

JSON

omitProtoReviver

β–Έ omitProtoReviver(key, value): unknown

Custom reviver that omits "__proto__" for safer parsing.

Parameters

NameTypeDescription
keystringCurrent key.
valueunknownCurrent value.

Returns

unknown

The current value or undefined if the key is "__proto__".

Remarks

JSON parsing has a proto poisoning vulnerability that can be exploited by passing a JSON string with a __proto__ key. This reviver can be used to prevent that.

Example

JSON.parse('{"__proto__":"😈"}', omitProto); // {}

See

parseJSON

View source


parseJSON

β–Έ parseJSON<Output>(...parameters): Maybe<Output>

Safely parses a JSON string or returns undefined if is invalid.

Type parameters

NameTypeDescription
Outputextends JSONValue = JSONValueGeneric of the output (has to be a JSONValue).

Parameters

NameType
...parameters[string: string]

Returns

Maybe<Output>

Parsed string or undefined if invalid JSON.

Remarks

JSON.parse is unsafe by default, allowing proto poisoning. This function takes care of it while making its types safer as well.

Example

parseJSON('{"__proto__":"😈"}'); // {}
parseJSON("invalid"); // undefined

See

View source

Number

parseBinary

β–Έ parseBinary(string): Maybe<number>

Parses a string to a binary number.

Parameters

NameTypeDescription
stringstringString to be parsed.

Returns

Maybe<number>

Parsed number or undefined if it fails.

Remarks

Parses a string to a binary number, returning undefined instead of NaN if it fails.

Example

parseBinary("101"); // 0b101 -> 5
parseBinary("101.5"); // 0b101 -> 5
parseBinary("invalid"); // undefined

See

parseInteger

View source


parseDecimal

β–Έ parseDecimal(string): Maybe<number>

Parses a string to a decimal number.

Parameters

NameTypeDescription
stringstringString to be parsed.

Returns

Maybe<number>

Parsed number or undefined if it fails.

Remarks

Parses a string to a decimal number, returning undefined instead of NaN if it fails.

Example

parseDecimal("101"); // 101
parseDecimal("101.5"); // 101
parseDecimal("invalid"); // undefined

See

parseInteger

View source


parseFloatingPoint

β–Έ parseFloatingPoint(string): Maybe<number>

Safe parseFloat alternative.

Parameters

NameTypeDescription
stringstringString to parse.

Returns

Maybe<number>

Parsed number or undefined if invalid.

Remarks

Parses a string to a float number. Returns undefined instead of NaN if it fails.

Example

parseFloatingPoint(10); // 10
parseFloatingPoint(13.1); // 13.1
parseFloatingPoint("invalid"); // undefined

See

undefineNaN

View source


parseHexadecimal

β–Έ parseHexadecimal(string): Maybe<number>

Parses a string to a hexadecimal number.

Parameters

NameTypeDescription
stringstringString to be parsed.

Returns

Maybe<number>

Parsed number or undefined if it fails.

Remarks

Parses a string to a hexadecimal number, returning undefined instead of NaN if it fails.

Example

parseHexadecimal("101"); // 0x101 -> 257
parseHexadecimal("101.5"); // 0x101 -> 257
parseHexadecimal("invalid"); // undefined

See

parseInteger

View source


parseInteger

β–Έ parseInteger(radix): (string: string) => Maybe<number>

Curried function to parse strings to numbers based on different radixes.

Parameters

NameTypeDescription
radixRadixRadix to use for parsing (16 for hexadecimal, 10 for decimal, and so on).

Returns

fn

Curried function with radix in context.

β–Έ (string): Maybe<number>

Curried function with radix set.

Parameters
NameTypeDescription
stringstringString to parse.
Returns

Maybe<number>

Parsed number or undefined if it fails.

See

Remarks

Parses a string to a number with the given radix, returning undefined instead of NaN if it fails.

Example

const parseDecimal = parseInteger(10);
parseDecimal("101"); // 101
parseDecimal("101.5"); // 101
parseDecimal("invalid"); // undefined

See

undefineNaN

View source


parseOctal

β–Έ parseOctal(string): Maybe<number>

Parses a string to a octal number.

Parameters

NameTypeDescription
stringstringString to be parsed.

Returns

Maybe<number>

Parsed number or undefined if it fails.

Remarks

Parses a string to a octal number, returning undefined instead of NaN if it fails.

Example

parseOctal("101"); // 0o101 -> 65
parseOctal("101.5"); // 0o101 -> 65
parseOctal("invalid"); // undefined

See

parseInteger

View source


undefineNaN

β–Έ undefineNaN<Number>(number): Maybe<Number>

NaN handler.

Type parameters

NameTypeDescription
Numberextends numberGeneric of the number to handle.

Parameters

NameTypeDescription
numberNumberNumber to handle.

Returns

Maybe<Number>

Number if it’s not NaN, otherwise undefined.

Remarks

Takes a number that could be NaN and makes it undefined if it is NaN.

Example

undefineNaN(10); // 10
undefineNaN(13.1); // 13.1
undefineNaN(NaN); // undefined

View source