Documentation

Overview

This module provides various functions for reading, validating, and processing JSON files and URL content.

Installation

npm install @terzogenito/json-utils

Quick Start

import jsonUtils from '@terzogenito/json-utils';

const jsonAttributes = jsonUtils.getAttributes(jsonData);
console.log(jsonAttributes);

Function List

1. getData(path)

console.log(await app.getData('./test-data.json'));

Description: Reads and returns data from a file asynchronously.

Parameters:

• path (String): Path to the file to be read

2. getString(path)

console.log(app.getString('test-data.json'));

Description: Reads a file and returns its content as a string.

Parameters:

• path (String): Path to the file to be read

3. getFile(path, callback)

app.getFile('test-data.json', data => {
    console.log(app.isValid(data));
});

Description: Reads a file and processes the data using a callback function.

Parameters:

• path (String): Path to the file to be read
• callback (Function): Function to be called with the file data

4. isValid(data)

app.getFile('test-data.json', data => {
    console.log(app.isValid(data));
});

Description: Validates whether the data is valid JSON.

Parameters:

• data (Any): Data to be validated

5. toString(data)

app.getFile('test-data.json', data => {
    console.log(app.toString(data));
});

Description: Converts JSON data to a string.

Parameters:

• data (Object): JSON data to be converted

6. readJSON(jsonString)

console.log(app.readJSON('{"name":"John","age":30,"isActive":true}'));

Description: Reads and parses a JSON string into a JavaScript object.

Parameters:

• jsonString (String): JSON string to be parsed

7. isJSON(jsonString)

console.log(app.isJSON('{"name":"John","age":30,"isActive":true}'));

Description: Checks if a string is valid JSON.

Parameters:

• jsonString (String): String to be checked

8. isJSONObject(obj)

console.log(app.isJSONObject({"name": "John","age": 30,"isActive": true}));

Description: Checks if an object is a valid JSON object.

Parameters:

• obj (Object): Object to be checked

9. beautifyJSON(jsonString, indent)

console.log(app.beautifyJSON(jsonString));
console.log(app.beautifyJSON(jsonString, 4));

Description: Formats a JSON string with customizable indentation.

Parameters:

• jsonString (String): JSON string to be formatted
• indent (Number, optional): Number of spaces for indentation (default: 2)

10. beautify(jsonObject)

console.log(app.beautify(sampleJSONObject));

Description: Formats a JSON object into a readable string.

Parameters:

• jsonObject (Object): JSON object to be formatted

11. getURL(url, callback)

app.getURL("https://example.com/data.txt", data => {
    console.log(data);
});

Description: Fetches string content from a URL.

Parameters:

• url (String): Target URL
• callback (Function): Callback function that receives the data

12. getJSON(url, callback)

app.getJSON("https://example.com/data.json", data => {
    console.log(data);
});

Description: Fetches and parses JSON content from a URL.

Parameters:

• url (String): URL pointing to JSON file
• callback (Function): Callback function that receives JSON data

Usage Examples

const app = require('./index');

// Reading local file
const data = await app.getData('./data.json');

// Validating JSON
const isValid = app.isJSON('{"key": "value"}');

// Formatting JSON
const beautified = app.beautifyJSON('{"key":"value"}', 4);

// Fetching data from URL
app.getJSON("https://api.example.com/data", jsonData => {
    console.log(jsonData);
});

13. getAttributes(jsonObject)

const dataJSON = app.readJSON(data);
const attributes = app.getAttributes(dataJSON);
// Output: ['name', 'age', 'isActive', 'address', 'hobbies']

Description: Extracts all attribute/keys from a JSON object and returns them as an array.

Parameters:

• jsonObject (Object|String): JSON object or JSON string

Returns: Array of attribute names

14. getMeta(jsonObject)

const meta = app.getMeta(dataJSON);
// Output: {"name": "string", "age": "integer", "isActive": "boolean"}

Description: Generates metadata showing attribute names and their data types.

Parameters:

• jsonObject (Object|String): JSON object or JSON string

Returns: Object with attribute names as keys and data types as values

Data Types Identified:

• string, integer, float, boolean, array, object, null, date

15. getMetaDetail(jsonObject)

const metaDetail = app.getMetaDetail(dataJSON);
// Output: Detailed metadata including nested structures

Description: Generates comprehensive metadata including nested attributes, data types, paths, and structural information.

Parameters:

• jsonObject (Object|String): JSON object or JSON string

Returns: Object with detailed metadata for each attribute

Metadata Includes:

• type: Data type
• isRequired: Whether attribute exists
• path: Full path to attribute
• children: Nested attributes (for objects)
• length: Array length (for arrays)
• elementType: Type of array elements

16. getMetaCompact(jsonObject)

const metaCompact = app.getMetaCompact(dataJSON);
// Output: Compact metadata format

Description: Creates a compact metadata representation showing the structure hierarchy.

Parameters:

• jsonObject (Object|String): JSON object or JSON string

Returns: Compact representation of JSON structure

Format Examples:

• "array[string]": Array of strings
• "array[object]": Array of objects
• Nested objects shown as nested objects

17. getPartial(jsonObject, attributes)

const partial = app.getPartial(dataJSON, ["name", "age"]);
// Output: {"name": "John", "age": 30}

Description: Extracts specific attributes from a JSON object.

Parameters:

• jsonObject (Object|String): JSON object or JSON string
• attributes (Array|String|Object): Attributes to extract

attribute Parameter Types:

• Array: List of attribute names to extract

app.getPartial(data, ["name", "age"])

• String: Single attribute name

app.getPartial(data, "name")

• Object: Mapping of new names to original attributes

app.getPartial(data, {"fullName": "name", "yearsOld": "age"})

Returns: Object containing only the specified attributes

18. getPartialDeep(jsonObject, attributePaths)

const deepPartial = app.getPartialDeep(dataJSON, ["name", "address.city", "hobbies.length"]);
// Output: {"name": "John", "city": "Jakarta", "length": 2}

Description: Extracts attributes using nested paths (dot notation).

Parameters:

• jsonObject (Object|String): JSON object or JSON string
• attributePaths (Array|Object): Paths to extract

attributePaths Parameter Types:

• Array: List of dot-notated paths

app.getPartialDeep(data, ["user.profile.name", "user.contact.email"])

• Object: Mapping of new names to paths

app.getPartialDeep(data, {"userName": "user.profile.name", "userEmail": "user.contact.email"})

Returns: Object with extracted values (uses last path segment as key for array input)

19. getPartialWithDefaults(jsonObject, attributesConfig)

const partialWithDefaults = app.getPartialWithDefaults(dataJSON, {
    "name": "name",
    "status": {
        path: "isActive",
        transform: (val) => val ? "Active" : "Inactive"
    },
    "email": {
        path: "contact.email",
        default: "[email protected]"
    }
});

Description: Extracts attributes with advanced configuration including default values and transformations.

Parameters:

• jsonObject (Object|String): JSON object or JSON string
• attributesConfig (Object): Configuration object

Configuration Options:

• String: Simple path extraction

"name": "user.fullName"

• Object: Advanced configuration

"formattedAge": {
    path: "age", // Required: Path to attribute
    default: 0, // Optional: Default value if path doesn't exist
    transform: (val) => ${val} years old // Optional: Transformation function
}

Returns: Object with extracted and processed values

20. excludeAttributes(jsonObject, attributesToExclude)

const filtered = app.excludeAttributes(dataJSON, ["isActive", "address"]);
// Output: {"name": "John", "age": 30, "hobbies": ["reading", "coding"]}

Description: Creates a new JSON object excluding specified attributes.

Parameters:

• jsonObject (Object|String): JSON object or JSON string
• attributesToExclude (Array|String): Attributes to remove

attributesToExclude Parameter Types:

• Array: List of attribute names to exclude

app.excludeAttributes(data, ["password", "secretKey"])

• String: Single attribute name to exclude

app.excludeAttributes(data, "password")

Returns: New object without the excluded attributes

21. getAttributeValue(jsonObject, attributeName, defaultValue)

const name = app.getAttributeValue(dataJSON, "name");
const email = app.getAttributeValue(dataJSON, "email", "[email protected]");

Description: Gets the value of a specific attribute with optional default value.

Parameters:

• jsonObject (Object|String): JSON object or JSON string
• attributeName (String): Name of the attribute to retrieve
• defaultValue (Any, optional): Default value if attribute doesn't exist

Returns: Attribute value or default value

Advanced Usage Examples

const app = require('./index');

// Get all attributes from JSON
const data = await app.getData('./data.json');
const jsonData = app.readJSON(data);
const attributes = app.getAttributes(jsonData);

// Get metadata information
const meta = app.getMeta(jsonData);
const metaDetail = app.getMetaDetail(jsonData);

// Extract specific data
const userInfo = app.getPartial(jsonData, ["name", "email", "phone"]);
const nestedData = app.getPartialDeep(jsonData, ["user.profile.name", "user.contact.email"]);

// Extract with transformations and defaults
const processedData = app.getPartialWithDefaults(jsonData, {
    "fullName": "user.name",
    "ageFormatted": {
        path: "user.age",
        transform: (age) => ${age} years old
    },
    "country": {
        path: "user.address.country",
        default: "Unknown"
    }
});

// Exclude sensitive information
const safeData = app.excludeAttributes(jsonData, ["password", "ssn", "creditCard"]);

// Analyze complex nested structures
const complexMeta = app.getMetaDetail(complexJSON);
console.log(complexMeta.user?.children?.contact?.children?.email?.type); // "string"

// Get single attribute value
const userName = app.getAttributeValue(jsonData, "name");
const userEmail = app.getAttributeValue(jsonData, "email", "[email protected]");

Requirements

• Node.js 12 or higher
• Internet connection (for URL functions)