json-parse-genie

A tiny, dependency-free TypeScript utility for safely parsing JSON with a clear success/failure result.

✨ Overview

json-parse-genie is a minimal and production-ready TypeScript utility that safely parses JSON strings without throwing runtime errors.

Instead of wrapping JSON.parse() in repetitive try/catch blocks throughout your codebase, this package provides a clean and predictable result object indicating success or failure.

It is ideal for:

• Backend APIs
• Configuration parsing
• User input validation
• Logging systems
• CLI tools
• Any environment where crashing on invalid JSON is unacceptable

🚀 Features

• 🛡 Never throws on invalid JSON
• 📦 Zero dependencies
• 🧩 Fully typed with TypeScript
• ⚡ Lightweight and fast
• 🔍 Clear success/error result structure
• 🔒 Safe for untrusted input

📦 Installation

npm install json-parse-genie

or

yarn add json-parse-genie

🔧 Usage

Basic Example

import { jsonParseGenie } from "json-parse-genie";

const result = jsonParseGenie('{"name":"Alice"}');

if (result.success) {
  console.log(result.data.name);
} else {
  console.error(result.error);
}

With Type Safety

type User = {
  id: number;
  name: string;
};

const result = jsonParseGenie<User>('{"id":1,"name":"Alice"}');

if (result.success) {
  console.log(result.data.id);
}

Handling Invalid JSON

const result = jsonParseGenie("{ invalid json }");

if (!result.success) {
  console.log(result.error); // "Invalid JSON"
}

No exceptions are thrown.

📖 API

jsonParseGenie<T = unknown>(input: string)

Safely parses a JSON string.

Parameters

Name Type Description

input string The JSON string to parse

Returns

type JsonParseGenieResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };

🧠 Why Not Just Use JSON.parse()?

JSON.parse() throws an exception on invalid input:

JSON.parse("{ invalid }"); // Throws

This forces usage of try/catch:

try {
  const data = JSON.parse(input);
} catch (err) {
  // handle error
}

With json-parse-genie, you get predictable results without repetitive boilerplate.

⚡ Performance

Internally uses native JSON.parse(). No overhead beyond a single try/catch block.

Benchmarks show negligible performance difference compared to manually wrapping JSON.parse().

🔒 Security

• No dynamic code execution
• No use of eval
• No external network requests
• No dependencies
• Safe for handling untrusted input strings

📁 Example Project Structure

json-parse-genie/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

🛠 Development

Clone the repository:

git clone https://github.com/devdream1111/json-parse-genie.git
cd json-parse-genie
npm install

Build:

npm run build

Test:

npm test

🤝 Contributing

Contributions are welcome.

If you'd like to improve performance, add tests, or suggest enhancements, please open an issue or submit a pull request.

📄 License

MIT © 2026 Your Name

⭐ Support

If you find this package useful, consider starring the repository and sharing it with the community.