@mastermindzh/composable-json-stringify

Composable JSON Stringify

A flexible and powerful library that extends JavaScript's native JSON.stringify with composable replacer functions.

The Problem with JSON.stringify

JavaScript's built-in JSON.stringify is powerful but has significant limitations when dealing with certain data types:

• BigInt values throw errors (commonly used in libraries like Kysely)
• Date objects are converted to strings without using ISO format
• Symbol values can't be stringified
• Function values are omitted
• Map and Set objects aren't serialized properly
• Error objects lose most of their information

Traditionally, to handle these cases, you'd have to write a complex replacer function that handles every edge case:

JSON.stringify(data, (key, value) => {
  if (typeof value === "bigint") return value.toString();
  if (value instanceof Date) return value.toISOString();
  if (typeof value === "symbol") return value.toString();
  if (value instanceof Error) return { name: value.name, message: value.message, stack: value.stack };
  // ... and so on for every type you need to handle
  return value;
});

This approach becomes unwieldy as your data gets more complex.

The Solution: Composable Replacers

This library lets you compose small, focused replacer functions (mixins) to handle specific data types:

import { stringify, bigIntToString, dateToISOString, symbolToString } from '@mastermindzh/composable-json-stringify';

const data = {
  id: 123456789n,
  name: "Example",
  created: new Date(),
  type: Symbol("user")
};

// Compose only the replacers you need
const json = stringify(data, [
  bigIntToString,
  dateToISOString,
  symbolToString
]);

Features

• 🧩 Composable - Mix and match replacers to fit your needs
• 🔌 Extensible - Create your own replacer mixins easily
• 🎯 Focused - Each replacer handles one specific data type
• 📦 Zero dependencies - Lightweight and efficient
• 🔍 Type-safe - Written in TypeScript with full type definitions

Installation

npm install @mastermindzh/composable-json-stringify

Available Replacers

The library comes with several pre-built replacers:

• bigIntToString - Converts BigInt values to strings
• symbolToString - Converts Symbol values to strings
• dateToISOString - Converts Date objects to ISO format strings
• undefinedToNull - Converts undefined values to null
• functionToString - Converts functions to "[Function]" strings
• errorToObject - Converts Error objects to serializable objects
• mapToObject - Converts Map objects to plain objects
• setToArray - Converts Set objects to arrays

Creating Custom Replacers

You can easily create your own replacer mixins:

import { ReplacerMixin } from '@mastermindzh/composable-json-stringify';

const customReplacer: ReplacerMixin = (key, value) => {
  if (key === "password") {
    return "[REDACTED]";
  }
  return value;
};

Creating a Custom stringify Function

You can export a custom stringify function with your preferred defaults:

import { stringify, bigIntToString, dateToISOString, undefinedToNull } from '@mastermindzh/composable-json-stringify';

// Create a custom stringify with your commonly used replacers
export const myStringify = (value, space) => {
  return stringify(value, [
    bigIntToString,
    dateToISOString,
    undefinedToNull
  ], space);
};

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.