jsonz

Zero dependencies JSON objects compression library written in TypeScript

• it works with JSON.stringify() therefore it inherits all its limitations for types serialization (check this)
• the compressed response is processed using the encodeURIComponent() method so it is URL friendly
• the compressSorted method recursively sort object keys and values before compressing
• this library works on Nodejs: to use it in the browser please refer to browserify-zlib
• fully typed with TypeScript - types are automatically included

Installation

npm install @ttessarolo/jsonz
# or
pnpm install @ttessarolo/jsonz
# or
yarn add @ttessarolo/jsonz

Types

The library exports the following functions with complete TypeScript types:

compress(data: unknown): string

Compresses a JSON object into a URL-friendly string.

Parameters:

• data: unknown - The object to compress (can be any value serializable with JSON.stringify)

Returns: string - A compressed and base64-encoded string, URL-friendly

compressSorted(data: unknown): string

Compresses a JSON object after recursively sorting all keys and values.

Parameters:

• data: unknown - The object to compress

Returns: string - A compressed and base64-encoded string, URL-friendly

decompress(data: string, parse?: boolean): unknown | Buffer

Decompresses a string previously generated by compress or compressSorted.

Parameters:

• data: string - The compressed string to decompress
• parse?: boolean - If true (default), returns the parsed JSON object. If false, returns the decompressed Buffer without parsing

Returns:

• unknown - When parse is true or omitted (default)
• Buffer - When parse is false

Overload TypeScript:

decompress(data: string): unknown
decompress(data: string, parse: false): Buffer

compressAsync(data: unknown): Promise<string>

Asynchronous version of compress. Compresses a JSON object into a URL-friendly string.

Parameters:

• data: unknown - The object to compress (can be any value serializable with JSON.stringify)

Returns: Promise<string> - A Promise that resolves to a compressed and base64-encoded string, URL-friendly

compressSortedAsync(data: unknown): Promise<string>

Asynchronous version of compressSorted. Compresses a JSON object after recursively sorting all keys and values.

Parameters:

• data: unknown - The object to compress

Returns: Promise<string> - A Promise that resolves to a compressed and base64-encoded string, URL-friendly

decompressAsync(data: string, parse?: boolean): Promise<unknown | Buffer>

Asynchronous version of decompress. Decompresses a string previously generated by compress, compressSorted, compressAsync or compressSortedAsync.

Parameters:

• data: string - The compressed string to decompress
• parse?: boolean - If true (default), returns the parsed JSON object. If false, returns the decompressed Buffer without parsing

Returns:

• Promise<unknown> - When parse is true or omitted (default)
• Promise<Buffer> - When parse is false

Overload TypeScript:

decompressAsync(data: string): Promise<unknown>
decompressAsync(data: string, parse: false): Promise<Buffer>

Examples

Basic Usage

import { compress, decompress } from "@ttessarolo/jsonz";

// Pure JSON object
const obj = {
  tenant: "japan",
  reference: "movies",
  ts: 1669997354214,
  blockId: "IN7AAWsmQIXjcp5x2yX3F",
  internalId: "VAhK7yqm4c575JDZ-QcC0",
  contentIds: ["Z", "A"],
  catalog: "objects",
  eventId: "view",
  subId: "YPZ-AtIlD6UuC-0HbhHyF"
};

// Compress and Decompress JSON Object
const compressed: string = compress(obj);
const decompressed: unknown = decompress(compressed);

console.log(decompressed);
// --> prints
// {
//   tenant: "japan",
//   reference: "movies",
//   ts: 1669997354214,
//   blockId: "IN7AAWsmQIXjcp5x2yX3F",
//   internalId: "VAhK7yqm4c575JDZ-QcC0",
//   contentIds: ["Z", "A"],
//   catalog: "objects",
//   eventId: "view",
//   subId: "YPZ-AtIlD6UuC-0HbhHyF",
// }

Compress Sorted

import { compressSorted, decompress } from "@ttessarolo/jsonz";

const obj = {
  tenant: "japan",
  reference: "movies",
  ts: 1669997354214,
  blockId: "IN7AAWsmQIXjcp5x2yX3F",
  contentIds: ["Z", "A"]
};

// Compress Sorted
const compressedOrdered: string = compressSorted(obj);
const decompressedOrdered: unknown = decompress(compressedOrdered);

console.log(decompressedOrdered);
// --> prints
// {
//   blockId: "IN7AAWsmQIXjcp5x2yX3F",
//   contentIds: ["A", "Z"],
//   reference: "movies",
//   tenant: "japan",
//   ts: 1669997354214
// }

Decompress with parse: false

When you need to get the decompressed Buffer without automatic parsing:

import { compress, decompress } from "@ttessarolo/jsonz";

const obj = {
  name: "test",
  value: 42
};

const compressed: string = compress(obj);

// Get the Buffer without parsing
const buffer: Buffer = decompress(compressed, false);

console.log(buffer instanceof Buffer); // true
console.log(buffer.toString()); // '{"name":"test","value":42}'

// You can parse manually if needed
const parsed: unknown = JSON.parse(buffer.toString());

Type-safe Usage

For type-safe usage, you can use type assertion after decompression:

import { compress, decompress } from "@ttessarolo/jsonz";

interface MyData {
  name: string;
  age: number;
  tags: string[];
}

const data: MyData = {
  name: "John",
  age: 30,
  tags: ["developer", "typescript"]
};

const compressed: string = compress(data);
const decompressed = decompress(compressed) as MyData;

console.log(decompressed.name); // "John"
console.log(decompressed.age); // 30

Async Functions

The library provides asynchronous versions of all compression and decompression functions:

Basic Async Usage

import { compressAsync, decompressAsync } from "@ttessarolo/jsonz";

const obj = {
  tenant: "japan",
  reference: "movies",
  ts: 1669997354214,
  blockId: "IN7AAWsmQIXjcp5x2yX3F",
  contentIds: ["Z", "A"]
};

// Using async/await
async function example() {
  const compressed: string = await compressAsync(obj);
  const decompressed: unknown = await decompressAsync(compressed);

  console.log(decompressed);
  // --> prints
  // {
  //   tenant: "japan",
  //   reference: "movies",
  //   ts: 1669997354214,
  //   blockId: "IN7AAWsmQIXjcp5x2yX3F",
  //   contentIds: ["Z", "A"]
  // }
}

// Using Promise chains
compressAsync(obj)
  .then((compressed: string) => decompressAsync(compressed))
  .then((decompressed: unknown) => {
    console.log(decompressed);
  });

Compress Sorted Async

import { compressSortedAsync, decompressAsync } from "@ttessarolo/jsonz";

const obj = {
  tenant: "japan",
  reference: "movies",
  ts: 1669997354214,
  blockId: "IN7AAWsmQIXjcp5x2yX3F",
  contentIds: ["Z", "A"]
};

async function example() {
  // Compress Sorted Async
  const compressedOrdered: string = await compressSortedAsync(obj);
  const decompressedOrdered: unknown = await decompressAsync(compressedOrdered);

  console.log(decompressedOrdered);
  // --> prints
  // {
  //   blockId: "IN7AAWsmQIXjcp5x2yX3F",
  //   contentIds: ["A", "Z"],
  //   reference: "movies",
  //   tenant: "japan",
  //   ts: 1669997354214
  // }
}

Decompress Async with parse: false

import { compressAsync, decompressAsync } from "@ttessarolo/jsonz";

const obj = {
  name: "test",
  value: 42
};

async function example() {
  const compressed: string = await compressAsync(obj);

  // Get the Buffer without parsing
  const buffer: Buffer = await decompressAsync(compressed, false);

  console.log(buffer instanceof Buffer); // true
  console.log(buffer.toString()); // '{"name":"test","value":42}'

  // You can parse manually if needed
  const parsed: unknown = JSON.parse(buffer.toString());
}

Error Handling

import { compressAsync, decompressAsync } from "@ttessarolo/jsonz";

async function example() {
  try {
    const compressed: string = await compressAsync({ data: "test" });
    const decompressed: unknown = await decompressAsync(compressed);
    console.log(decompressed);
  } catch (error) {
    console.error("Compression/Decompression error:", error);
  }
}

API Reference

Functions

compress(data: unknown): string

Compresses a JSON object into a compressed and encoded string.

compressSorted(data: unknown): string

Recursively sorts the keys and values of an object and compresses it.

decompress(data: string, parse?: boolean): unknown | Buffer

Decompresses a compressed string.

• With parse: true (default): returns the parsed JSON object as unknown
• With parse: false: returns the decompressed Buffer without parsing

compressAsync(data: unknown): Promise<string>

Asynchronous version of compress. Compresses a JSON object into a compressed and encoded string. Returns a Promise that resolves with the compressed string.

compressSortedAsync(data: unknown): Promise<string>

Asynchronous version of compressSorted. Recursively sorts the keys and values of an object and compresses it. Returns a Promise that resolves with the compressed string.

decompressAsync(data: string, parse?: boolean): Promise<unknown | Buffer>

Asynchronous version of decompress. Decompresses a compressed string. Returns a Promise that resolves with the decompressed data.

• With parse: true (default): returns a Promise that resolves to the parsed JSON object as unknown
• With parse: false: returns a Promise that resolves to the decompressed Buffer without parsing

License

«Copyright (c) 2022, Tommaso Tessarolo

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.»