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
1
pnpm add @lou.codes/parsers
2
# or
3
npm install @lou.codes/parsers
4
# or
5
yarn add @lou.codes/parsers

Import it and use it:

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

πŸ¦• Deno

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

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

🌎 Browser

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

1
<script type="module">
2
import { parseDecimal } from "https://esm.sh/@lou.codes/parsers";
3
4
parseDecimal("101"); // 101
5
parseDecimal("nope"); // undefined
6
</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

1
const willFail = () => {
2
throw new Error("fail");
3
};
4
5
const safeWillFail = attempt(willFail);
6
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

1
clone({ foo: "bar" }); // { foo: "bar" }
2
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

1
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

1
parseJSON('{"__proto__":"😈"}'); // {}
2
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

1
parseBinary("101"); // 0b101 -> 5
2
parseBinary("101.5"); // 0b101 -> 5
3
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

1
parseDecimal("101"); // 101
2
parseDecimal("101.5"); // 101
3
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

1
parseFloatingPoint(10); // 10
2
parseFloatingPoint(13.1); // 13.1
3
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

1
parseHexadecimal("101"); // 0x101 -> 257
2
parseHexadecimal("101.5"); // 0x101 -> 257
3
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

1
const parseDecimal = parseInteger(10);
2
3
parseDecimal("101"); // 101
4
parseDecimal("101.5"); // 101
5
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

1
parseOctal("101"); // 0o101 -> 65
2
parseOctal("101.5"); // 0o101 -> 65
3
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

1
undefineNaN(10); // 10
2
undefineNaN(13.1); // 13.1
3
undefineNaN(NaN); // undefined

View source