@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