jsonshrinkify

Ultra-fast TypeScript JSON minifier and sanitizer for React apps, APIs and browser delivery.

A production-grade, dependency-free TypeScript library for JSON minification, sanitization, normalization, validation, streaming experiments, worker execution and WASM-ready acceleration.

This README merges the package-focused concise README you provided fileciteturn0file0 with a full production-grade package README structure into one publish-ready document.

Shrink JSON. Keep correctness. Scale everywhere.

Contents

• Why jsonshrinkify
• Features
• Installation
• Quick Start
• Core APIs
• Options
• Safe APIs
• File Helpers
• Async APIs
• Schema Validation
• Streaming Engine
• Worker Support
• WASM Experiments
• React / Node Examples
• Benchmarks
• CLI
• Performance Notes
• Architecture
• Security
• Compatibility
• FAQ
• Development
• Publishing
• License

Why jsonshrinkify

Most JSON “minifiers” stop at:

JSON.stringify(JSON.parse(input));

jsonshrinkify goes much further.

It is designed for:

• React applications
• Browser bundles
• Node.js APIs
• Edge runtimes
• Web Workers
• Large payload systems
• Build pipelines
• TypeScript libraries
• Long-term production use

It combines:

• Fast minification
• Safe sanitization
• Stable normalization
• Byte savings reporting
• Schema validation
• Streaming parser foundations
• Worker support
• WASM-ready adapters

Features

Core

• Minify JSON strings
• Minify JavaScript objects into compact JSON
• Sanitize unsafe values before JSON output
• Handle circular references
• Convert invalid numbers safely
• Stable key ordering
• Byte statistics for shrink results
• Zero runtime dependencies
• Written in TypeScript

Advanced

• Safe non-throwing APIs
• Browser entrypoint
• Node entrypoint
• File minification helpers
• Async APIs
• Schema validation layer
• Streaming optimization APIs
• Streaming parser engine
• Web Worker support
• WASM experiment layer

Installation

npm

npm install jsonshrinkifyify

pnpm

pnpm add jsonshrinkify

yarn

yarn add jsonshrinkify

Package Entry Points

Default

import { minifyJson, shrinkJson } from "jsonshrinkify";

Browser

import { minifyJson, normalizeJson } from "jsonshrinkify/browser";

Node

import { minifyJsonFile } from "jsonshrinkify/node";

Worker

import { handleJsonShrinkWorkerRequest } from "jsonshrinkify/worker";

WASM

import { hybridMinifyJson } from "jsonshrinkify/wasm";

Quick Start

Minify JSON String

import { minifyJson } from "jsonshrinkify";

const json = `{
  "name": "jsonshrinkify",
  "enabled": true
}`;

console.log(minifyJson(json));

Output:

{ "name": "jsonshrinkify", "enabled": true }

Minify Object

import { minifyJson } from "jsonshrinkify";

const result = minifyJson({
  app: "jsonshrinkify",
  version: 1,
  enabled: true,
});

Get Byte Savings

import { shrinkJson } from "jsonshrinkify";

const result = shrinkJson(input);

console.log(result.savedPercent);

Returns:

interface JsonShrinkResult {
  value: string;
  bytes: number;
  originalBytes: number;
  savedBytes: number;
  savedPercent: number;
}

Core APIs

minifyJson

minifyJson(
 input,
 options?
)

Minifies:

• JSON strings
• Objects
• Arrays

Example:

minifyJson({
  a: 1,
  b: true,
});

stringifyJson

stringifyJson(
 value,
 options?
)

Supports:

• sanitization
• stable keys
• circular handling
• invalid number handling

Example:

stringifyJson(data, {
  sanitize: true,
  stableKeys: true,
  circular: "null",
});

sanitizeJsonValue

sanitizeJsonValue(
 input,
 options?
)

Example:

sanitizeJsonValue({
  value: undefined,
  bad: Number.NaN,
});

shrinkJson

shrinkJson(
 input,
 options?
)

Returns:

• minified value
• byte stats
• savings percentages

normalizeJson

normalizeJson(data);

Useful for:

• hashing
• snapshots
• deterministic output
• cache keys

prettyJson

prettyJson(input, 2);

parseJson

parseJson<T>(input);

Throws on invalid JSON.

safeParseJson

const result = safeParseJson(input);

if (result.ok) {
  console.log(result.value);
}

Options

interface JsonShrinkOptions {
  sanitize?: boolean;
  circular?: "throw" | "null" | "omit";
  invalidNumber?: "null" | "string" | "throw";
  omitUndefined?: boolean;
  omitFunctions?: boolean;
  omitSymbols?: boolean;
  stableKeys?: boolean;
}

sanitize

Default:

false;

minifyJson(input, {
  sanitize: true,
});

circular

Options:

"throw";
"null";
"omit";

Example:

stringifyJson(data, {
  sanitize: true,
  circular: "null",
});

invalidNumber

Options:

"null";
"string";
"throw";

stableKeys

stringifyJson(data, {
  sanitize: true,
  stableKeys: true,
});

Safe APIs

Non-throwing APIs:

safeMinifyJson();
safeShrinkJson();
safeStringifyJson();
safeNormalizeJson();

Example:

const result = safeMinifyJson(payload);

if (result.ok) {
  send(result.value);
}

File Helpers

Minify File

import { minifyJsonFile } from "jsonshrinkify";

minifyJsonFile("input.json", {
  output: "output.min.json",
});

File Stats

import { shrinkJsonFile } from "jsonshrinkify";

const stats = shrinkJsonFile("input.json");

Async APIs

await minifyJsonAsync(data);
await shrinkJsonAsync(data);
await parseJsonAsync(json);
await minifyJsonFileAsync(file);

Schema Validation

Define Schema

const schema = {
  type: "object",
  required: ["name"],
  properties: {
    name: {
      type: "string",
    },
  },
};

Validate

validateJsonSchema(data, schema);

Typed Validator

const validator = createValidator<{
  name: string;
}>(schema);

Sanitize + Validate

sanitizeAndValidate(data, schema);

Streaming APIs

Progressive Minify

progressiveMinifyJson(input);

Chunk Utilities

chunkString(input);

Streaming Parser Engine

streamMinifyJsonUnsafe();
streamMinifyJson();

Unsafe:

• parser-state whitespace stripping

Safe:

• validates output correctness

Worker Support

handleJsonShrinkWorkerRequest({
  id: "1",
  action: "minify",
  input: { ok: true },
});

Supported actions:

• minify
• shrink
• stringify
• normalize
• pretty

Dedicated runtime:

import "jsonshrinkify/worker/runtime";

WASM Experiments

import {
  detectWasmSupport,
  wasmMinifyJson,
  hybridMinifyJson,
} from "jsonshrinkify/wasm";

Current:

• feature detection
• adapter abstraction
• hybrid routing
• JS fallback

Future:

• Rust backend
• wasm-pack
• serde_json experiments
• SIMD research

React Example

import { minifyJson } from "jsonshrinkify/browser";

export function Preview() {
  const payload = {
    app: "react",
  };

  return <pre>{minifyJson(payload)}</pre>;
}

Node API Example

import http from "node:http";
import { minifyJson } from "jsonshrinkify";

http.createServer((_req, res) => {
  res.end(minifyJson(payload));
});

Error Handling

import { minifyJson, JsonShrinkError } from "jsonshrinkify";

try {
  minifyJson("{ invalid json }");
} catch (error) {
  if (error instanceof JsonShrinkError) {
    console.error(error.code);
  }
}

Error codes:

• JSONSHRINK_INVALID_JSON
• JSONSHRINK_CIRCULAR_REFERENCE
• JSONSHRINK_INVALID_NUMBER
• JSONSHRINK_STRINGIFY_FAILED

Benchmarks

Run:

npm run benchmark:suite

Huge payload:

npm run benchmark:huge

Streaming parser:

npm run benchmark:stream

WASM experiments:

npm run benchmark:wasm

CLI

jsonshrinkify --input data.json --output data.min.json

Stats:

jsonshrinkify -i data.json --stats

Performance Notes

Optimized for practical production use.

Strategies:

• native JSON parse/stringify paths
• opt-in sanitization
• opt-in key sorting
• zero runtime dependencies

Maximum speed:

minifyJson(validJsonString);

Maximum safety:

minifyJson(unknownInput, {
  sanitize: true,
  circular: "null",
  invalidNumber: "null",
});

Architecture

src/
 core minifier
 sanitize layer
 parse helpers
 schema validation
 async helpers
 streaming engine
 worker support
 wasm adapters
 cli

Principles:

• Zero runtime dependencies
• Stable APIs
• Long-term compatibility
• Browser safety
• Production hardening

Security

jsonshrinkify:

• does not execute JSON
• avoids eval
• favors deterministic output
• does not depend on external parsers

Compatibility

Supports:

• Modern browsers
• Node 18+
• Bun
• Deno adapters
• Cloudflare Workers
• Vercel Edge
• React
• Next.js
• Vite

FAQ

Why not just JSON.stringify?

Because jsonshrinkify adds:

• sanitization
• validation
• stable normalization
• streaming support
• workers
• wasm adapters

Is this compression?

No.

Structural minification.

Use gzip/brotli additionally.

Can it handle huge payloads?

Yes.

Use:

• streaming helpers
• worker support
• benchmark tooling

Development

npm install
npm run check
npm run benchmark:suite

Publishing

npm run prepublishOnly
npm publish --access public

Semantic release supported.

Contributing

Conventional commits:

feat:
fix:
perf:
docs:
test:

PRs welcome.

License

MIT

Tagline

Shrink JSON. Keep correctness. Scale everywhere.