https://github.com/devnax/json-piece
json-piece is a lightweight JavaScript package that provides two main functions: toString and parse
https://github.com/devnax/json-piece
json-stringify
Last synced: 6 months ago
JSON representation
json-piece is a lightweight JavaScript package that provides two main functions: toString and parse
- Host: GitHub
- URL: https://github.com/devnax/json-piece
- Owner: devnax
- License: mit
- Created: 2022-06-12T08:06:43.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-07-04T17:33:58.000Z (7 months ago)
- Last Synced: 2025-07-04T18:41:37.308Z (7 months ago)
- Topics: json-stringify
- Language: TypeScript
- Homepage: https://npmjs.com/package/json-piece
- Size: 152 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `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:
```bash
npm install json-piece
```
Alternatively, you can use yarn:
```bash
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
```javascript
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
```javascript
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
```javascript
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
```javascript
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](https://github.com/devnax/json-piece/blob/main/LICENSE) for more details.
---
## 🤝 Contributing
Contributions are welcome! Please check out the [contribution guidelines](https://github.com/devnax/json-piece).
---
## 📄 License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
---
## 📞 Support
For help or suggestions, feel free to open an issue on [GitHub](https://github.com/devnax/json-piece/issues) or contact us via [devnaxrul@gmail.com](mailto:devnaxrul@gmail.com).