Parsers Reference

Coverage License NPM Version Open Issues

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

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>

Useful links

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

Common

attempt()

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

Wrapper for try/catch.

Type parameters

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

Parameters

Parameter	Type	Description
`wrappedFunction`	(…`wrappedArguments`: `Arguments`) => `Output`	Function to be wrapped.

Returns

Function

Function wrapped in try/catch.

Parameters

Parameter	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

1
const willFail = () => {
2
	throw new Error("fail");
3
};
4

5
const safeWillFail = attempt(willFail);
6
safeWillFail(); // undefined

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 parameter	Description
`Type`	Type of the value to be cloned.

Parameters

Parameter	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

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

See

JSON

omitProtoReviver()

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

Custom reviver that omits "__proto__" for safer parsing.

Parameters

Parameter	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

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

See

parseJSON

parseJSON()

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

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

Type parameters

Type parameter	Value	Description
`Output` extends `JSONValue`	`JSONValue`	Generic of the output (has to be a `JSONValue`).

Parameters

Parameter	Type
…`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

Number

parseBinary()

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

Parses a string to a binary number.

Parameters

Parameter	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

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

See

parseInteger

parseDecimal()

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

Parses a string to a decimal number.

Parameters

Parameter	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

1
parseDecimal("101"); // 101
2
parseDecimal("101.5"); // 101
3
parseDecimal("invalid"); // undefined

See

parseInteger

parseFloatingPoint()

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

Safe parseFloat alternative.

Parameters

Parameter	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

1
parseFloatingPoint(10); // 10
2
parseFloatingPoint(13.1); // 13.1
3
parseFloatingPoint("invalid"); // undefined

See

undefineNaN

parseHexadecimal()

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

Parses a string to a hexadecimal number.

Parameters

Parameter	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

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

See

parseInteger

parseInteger()

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

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

Parameters

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

Parameter	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

1
const parseDecimal = parseInteger(10);
2

3
parseDecimal("101"); // 101
4
parseDecimal("101.5"); // 101
5
parseDecimal("invalid"); // undefined

See

undefineNaN

parseOctal()

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

Parses a string to a octal number.

Parameters

Parameter	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

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

See

parseInteger

undefineNaN()

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

NaN handler.

Type parameters

Type parameter	Description
`Number` extends `number`	Generic of the number to handle.

Parameters

Parameter	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

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