json-piece Documentation

Overview

json-piece is a lightweight JavaScript package that provides two main functions: toString and parse. It allows you to easily convert JSON objects or arrays to a string representation, and vice versa. This is useful for encoding and decoding complex JSON structures while maintaining their integrity and ensuring they can be easily transmitted or stored.

• toString: Converts a JSON object or array into a string.
• parse: Converts a string representation back into the original JSON object or array.

Installation

To install the json-piece package, you can use npm:

npm install json-piece

Alternatively, you can use yarn:

yarn add json-piece

Functions

toString

The toString function takes a JSON object or array and converts it into a string representation. Nested objects and arrays are properly handled, ensuring the structure remains intact.

Usage

import { toString } from 'json-piece';

const obj = {
  a: 1,
  b: [2, 3],
  c: { d: 4, e: 5 }
};

const jsonString = toString(obj);
console.log(jsonString); // Encoded string representation of the object

Parameters

• data: The JSON object or array to convert into a string.

Returns

• A string representation of the given JSON object or array. The string is encoded with encodeURI to make it URL-safe.

parse

The parse function converts a string representation generated by toString back into its original JSON object or array form. This function ensures the nested structures are properly reconstructed.

Usage

import { parse } from 'json-piece';

const jsonString = '[a&b&c]/0{a=1&b=2|1[a&b&c]}';

const parsedObj = parse(jsonString);
console.log(parsedObj); // Reconstructed original object

Parameters

• data: The string representation of a JSON object or array, typically generated by the toString function.

Returns

• The original JSON object or array.

How It Works

The package works by serializing each object or array into a structured format, where nested objects and arrays are assigned an index and represented as references. These references are stored in a pieces array and are later used during parsing to reconstruct the original structure.

1. toString:

   • Iterates over the data, identifies whether an item is an object, array, or primitive value, and processes it accordingly.
   • Nested objects and arrays are serialized with unique references, which are stored in the pieces array.
   • The final string is a combination of the root structure and the serialized references.

2. parse:

   • The string is split into root and pieces.
   • The references are resolved using the pieces array, and the original objects and arrays are reconstructed.

Example

Example 1: Object to String

const myObject = {
  name: "Alice",
  age: 30,
  address: {
    street: "123 Main St",
    city: "Wonderland"
  }
};

const stringified = toString(myObject);
console.log(stringified);
// Output: Encoded string representation of the object

Example 2: String to Object

const stringified = '[a&b&c]/0{a=1&b=2|1[a&b&c]}';

const parsedObject = parse(stringified);
console.log(parsedObject);
// Output: The original object structure

License

This package is licensed under the MIT License. See LICENSE for more details.

---

🤝 Contributing

Contributions are welcome! Please check out the contribution guidelines.

---

📄 License

This project is licensed under the MIT License.

---

📞 Support

For help or suggestions, feel free to open an issue on GitHub or contact us via [email protected].