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()

1
function attempt<Arguments, Output>(
2
wrappedFunction: (...wrappedArguments: Arguments) => Output,
3
): (...parameters: Arguments) => Maybe<Output>;

Wrapper for try/catch.

Type parameters

Type parameterDescription
Arguments extends ReadOnlyArrayType of the arguments of the function to be wrapped.
Output-

Parameters

ParameterTypeDescription
wrappedFunction(โ€ฆwrappedArguments: Arguments) => OutputFunction to be wrapped.

Returns

Function

Function wrapped in try/catch.

Parameters
ParameterType
โ€ฆ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()

1
function clone<Type>(value: Type): Maybe<Type>;

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

Type parameters

Type parameterDescription
TypeType of the value to be cloned.

Parameters

ParameterTypeDescription
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()

1
function omitProtoReviver(key: string, value: unknown): unknown;

Custom reviver that omits "__proto__" for safer parsing.

Parameters

ParameterTypeDescription
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()

1
function parseJSON<Output>(...parameters: [string]): Maybe<Output>;

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

Type parameters

Type parameterValueDescription
Output extends JSONValueJSONValueGeneric of the output (has to be a JSONValue).

Parameters

ParameterType
โ€ฆparameters[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()

1
function parseBinary(string: string): Maybe<number>;

Parses a string to a binary number.

Parameters

ParameterTypeDescription
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()

1
function parseDecimal(string: string): Maybe<number>;

Parses a string to a decimal number.

Parameters

ParameterTypeDescription
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()

1
function parseFloatingPoint(string: string): Maybe<number>;

Safe parseFloat alternative.

Parameters

ParameterTypeDescription
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()

1
function parseHexadecimal(string: string): Maybe<number>;

Parses a string to a hexadecimal number.

Parameters

ParameterTypeDescription
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()

1
function parseInteger(radix: Radix): (string: string) => Maybe<number>;

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

Parameters

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

Returns

Function

Curried function with radix in context.

Curried function with radix set.

Parameters
ParameterTypeDescription
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()

1
function parseOctal(string: string): Maybe<number>;

Parses a string to a octal number.

Parameters

ParameterTypeDescription
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()

1
function undefineNaN<Number>(number: Number): Maybe<Number>;

NaN handler.

Type parameters

Type parameterDescription
Number extends numberGeneric of the number to handle.

Parameters

ParameterTypeDescription
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