@philiprehberger/safe-parse

Safe parsing for primitives — numbers, booleans, dates, JSON from unknown strings

Installation

npm install @philiprehberger/safe-parse

Usage

Parse numbers

import { parseNumber, parseInteger, parseFloat } from "@philiprehberger/safe-parse";

parseNumber("42");        // 42
parseNumber("abc");       // undefined
parseNumber("Infinity");  // undefined

parseInteger("3.14");     // undefined
parseInteger("10");       // 10

parseFloat("3.14159", { precision: 2 }); // 3.14

Parse booleans

import { parseBoolean } from "@philiprehberger/safe-parse";

parseBoolean("true");  // true
parseBoolean("yes");   // true
parseBoolean("0");     // false
parseBoolean("off");   // false
parseBoolean("maybe"); // undefined

Parse dates

import { parseDate } from "@philiprehberger/safe-parse";

parseDate("2026-01-15");         // Date object
parseDate("not a date");         // undefined

Parse JSON

import { parseJSON } from "@philiprehberger/safe-parse";

parseJSON('{"key": "value"}');   // { key: "value" }
parseJSON("invalid json");      // undefined

Parse URLs

import { parseURL } from "@philiprehberger/safe-parse";

parseURL("https://example.com");                       // URL instance
parseURL("ftp://example.com");                         // undefined (default protocols allow only http/https)
parseURL("ftp://example.com", { protocols: ["ftp:"] }); // URL instance
parseURL("/foo", { base: "https://example.com" });     // URL → https://example.com/foo
parseURL("javascript:alert(1)", { protocols: null });  // URL — pass null to allow any protocol

Batch coerce with schema

import { coerce } from "@philiprehberger/safe-parse";

const query = { page: "3", active: "true", since: "2026-01-01", tags: "a,b,c" };

const parsed = coerce(query, {
  page: "number",
  active: "boolean",
  since: "date",
  tags: "string[]",
});
// { page: 3, active: true, since: Date, tags: ["a", "b", "c"] }

Fallback defaults

import { parseNumberOrDefault, parseBooleanOrDefault } from "@philiprehberger/safe-parse";

parseNumberOrDefault("abc", 0);     // 0
parseBooleanOrDefault("yes", false); // true

API

Function	Input	Output
parseNumber(input)	unknown	number | undefined
parseInteger(input)	unknown	number | undefined
parseFloat(input, options?)	unknown	number | undefined
parseBoolean(input)	unknown	boolean | undefined
parseDate(input)	unknown	Date | undefined
parseJSON<T>(input)	unknown	T | undefined
parseURL(input, options?)	unknown	URL | undefined
parseArray(input, separator?)	unknown	string[] | undefined
coerce(input, schema)	Record<string, unknown>	CoerceResult<S>
parseNumberOrDefault(input, fallback)	unknown, number	number
parseBooleanOrDefault(input, fallback)	unknown, boolean	boolean
parseDateOrDefault(input, fallback)	unknown, Date	Date
parseJSONOrDefault<T>(input, fallback)	unknown, T	T

ParseURLOptions

Option	Type	Default	Description
protocols	readonly string[] | null	['http:', 'https:']	Allowed protocols. null allows any.
base	string | URL	undefined	Base URL used to resolve relative inputs.

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT