Parsers by Lou

👁️‍🗨️ 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:

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>

Useful links

• 📝 Documentation: TypeDoc generated documentation.
• ⏳ Changelog: List of changes between versions.
• ✅ Tests Coverage: Coveralls page with tests coverage.

Common

attempt

▸ attempt<Arguments, Output>(wrappedFunction): (…parameters: Arguments) => Maybe<Output>

Wrapper for try/catch.

Type parameters

Name	Type	Description
Arguments	extends ReadOnlyArray	Type of the arguments of the function to be wrapped.
Output	Output	-

Parameters

Name	Type	Description
wrappedFunction	Function<Arguments, Output>	Function to be wrapped.

Returns

fn

Function wrapped in try/catch.

▸ (...parameters): Maybe<Output>

Parameters

Name	Type
...parameters	Arguments

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

Name	Description
Type	Type of the value to be cloned.

Parameters

Name	Type	Description
value	Type	Value 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

• attempt
• structuredClone

View source

JSON

omitProtoReviver

▸ omitProtoReviver(key, value): unknown

Custom reviver that omits "__proto__" for safer parsing.

Parameters

Name	Type	Description
key	string	Current key.
value	unknown	Current 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

Name	Type	Description
Output	extends JSONValue = JSONValue	Generic of the output (has to be a JSONValue).

Parameters

Name	Type
...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

• attempt
• omitProtoReviver

View source

Number

parseBinary

▸ parseBinary(string): Maybe<number>

Parses a string to a binary number.

Parameters

Name	Type	Description
string	string	String 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

Name	Type	Description
string	string	String 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

Name	Type	Description
string	string	String 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

Name	Type	Description
string	string	String 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

Name	Type	Description
radix	Radix	Radix 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

Name	Type	Description
string	string	String to parse.

Returns

Maybe<number>

Parsed number or undefined if it fails.

See

• undefineNaN
• parseInteger

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

Name	Type	Description
string	string	String 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

Name	Type	Description
Number	extends number	Generic of the number to handle.

Parameters

Name	Type	Description
number	Number	Number 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