Skip to content

Handy Script JSON Documentation

Jump to bottom
whybe edited this page Sep 26, 2023 · 2 revisions

The JSON module extends the JSON object for more functionality and ease of use. when dealing with JSON objects in JavaScript.

© HandyScript JSON 6/16/23 - Last Update: 9/25/23:

Table of Contents

Methods

isValid

The isValid method checks if a string is a valid JSON string.

JSON.isValid(json: string): boolean

Parameters:

  • json - The JSON string to check

Returns: - true if the string is a valid JSON string, false otherwise

Example:

const json = `{
  "name": "John",
  "age": 20,
  "weight": 70,
  "height": 180,
  "isMarried": true,
  "isStudent": true
}`;
console.log(JSON.isValid(json)); // true

flatten

The flatten method flattens a JSON object into a single level object.

JSON.flatten(json: JsonObject, prefix: string): FlattenedObject;

Parameters:

  • json - The JSON object to flatten should be a valid JSON object type of JsonObject.
  • prefix - The prefix to add to the keys of the flattened object.

Returns: - The flattened object, type of FlattenedObject.

Example:

const json = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
};
console.log(JSON.flatten(json, "person"));

Output:

{
  "person.name": "John",
  "person.age": 20,
  "person.weight": 70,
  "person.height": 180,
  "person.address.city": "Marrakech",
  "person.address.country": "Morocco"
}

unflatten

The unflatten method unflattens a flattened JSON object into a nested JSON object.

JSON.unflatten(json: FlattenedObject): JsonObject;

Parameters:

  • json - The flattened JSON object to unflatten should be a valid JSON object type of FlattenedObject.

Returns: - The unflattened object, type of JsonObject.

Example:

const json = {
  "person.name": "John",
  "person.age": 20,
  "person.weight": 70,
  "person.height": 180,
  "person.address.city": "Marrakech",
  "person.address.country": "Morocco",
};
console.log(JSON.unflatten(json));

Output:

{
  "person": {
    "name": "John",
    "age": 20,
    "weight": 70,
    "height": 180,
    "address": {
      "city": "Marrakech",
      "country": "Morocco"
    }
  }
}

merge

The merge method merges all the inputed JSON objects into a single JSON object with the keys-values merged.

JSON.merge(...jsonData: JsonObject[]): JsonObject;

Parameters:

  • jsonData - The JSON objects to merge should be a valid JSON object type of JsonObject.

Returns: - The merged object, type of JsonObject.

Example:

const json1 = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
};

const json2 = {
  name: "Ali",
  age: 30,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
  hobbies: ["football", "basketball", "tennis"],
};

console.log(JSON.merge(json1, json2));

Output:

{
  "name": "Ali",
  "age": 30,
  "weight": 70,
  "height": 180,
  "address": {
    "city": "Marrakech",
    "country": "Morocco"
  },
  "hobbies": ["football", "basketball", "tennis"],
}

filter

The filter method filters a JSON object by the specified keys. and a condition callback function.

JSON.filter(json: JsonObject, condition: (value: JsonValue) => boolean): JsonObject;

Parameters:

  • json - The JSON object to filter should be a valid JSON object type of JsonObject.
  • condition - The condition callback function to filter the JSON object.
  • condition.value - The value of the current key-value pair in the JSON object. type of JsonValue.

Returns: - The filtered object, type of JsonObject.

Example:

const json = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
  hobbies: ["football", "basketball", "tennis"],
};

console.log(JSON.filter(json, (value) => typeof value === "string"));

Output:

{
  "name": "John",
  "address": {
    "city": "Marrakech",
    "country": "Morocco"
  }
}

sort

The sort method sorts a JSON object by the specified key. and an order.

JSON.sort(json: JsonObject[], key: string, order: SortOrder = "asc"): JsonObject[];

Parameters:

  • json - The JSON object to sort should be a valid JSON object type of JsonObject.
  • key - The key to sort the JSON object by.
  • order - The order to sort the JSON object by. type of SortOrder.

Returns: - The sorted object, type of JsonObject.

Example:

const json = [
  {
    name: "John",
    age: 20,
    weight: 70,
    height: 180,
    address: {
      city: "Marrakech",
      country: "Morocco",
    },
    hobbies: ["football", "basketball", "tennis"],
  },
  {
    name: "Ali",
    age: 30,
    weight: 70,
    height: 180,
    address: {
      city: "Marrakech",
      country: "Morocco",
    },
    hobbies: ["football", "basketball", "tennis"],
  },
];

console.log(JSON.sort(json, "age", "desc"));

Output:

[
  {
    "name": "Ali",
    "age": 30,
    "weight": 70,
    "height": 180,
    "address": {
      "city": "Marrakech",
      "country": "Morocco"
    },
    "hobbies": ["football", "basketball", "tennis"],
  },
  {
    "name": "John",
    "age": 20,
    "weight": 70,
    "height": 180,
    "address": {
      "city": "Marrakech",
      "country": "Morocco"
    },
    "hobbies": ["football", "basketball", "tennis"],
  }
]

pluck

The pluck method plucks a JSON object by the specified keys, and Return an array of values of a key in a JSON object

JSON.pluck(json: JsonObject[], key: string): JsonData[]

Parameters:

  • json - The JSON object to pluck should be a valid JSON object type of JsonObject.
  • key - The key to pluck the JSON object by.

Returns: - The plucked object, type of JsonData.

Example:

const json = [
  {
    name: "John",
    age: 20,
    weight: 70,
    height: 180,
    address: {
      city: "Marrakech",
      country: "Morocco",
    },
    hobbies: ["football", "basketball", "tennis"],
  },
  {
    name: "Ali",
    age: 30,
    weight: 70,
    height: 180,
    address: {
      city: "Marrakech",
      country: "Morocco",
    },
    hobbies: ["football", "basketball", "tennis"],
  },
];

console.log(JSON.pluck(json, "name"));

Output:

["John", "Ali"]

transform

The transform method transforms a JSON object by a mapping JSON object.

JSON.transform(json: JsonObject, mapping: JsonObject): JsonObject;

Parameters:

  • json - The JSON object to transform should be a valid JSON object type of JsonObject.
  • mapping - The mapping JSON object to transform the JSON object by should be a valid JSON object type of JsonObject.

Returns: - The transformed object, type of JsonObject.

Example:

const json = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
  hobbies: ["football", "basketball", "tennis"],
};

const mapping = {
  name: "fullname",
  age: "age",
  weight: "weight",
  height: "height",
  address: {
    city: "city",
    country: "country",
  },
  hobbies: "hobbies",
};

console.log(JSON.transform(json, mapping));

Output:

{
  "fullname": "John",
  "age": 20,
  "weight": 70,
  "height": 180,
  "address": {
    "city": "Marrakech",
    "country": "Morocco"
  },
  "hobbies": ["football", "basketball", "tennis"],
}

validateSchema

The validateSchema method validates a JSON object against a schema JSON Schema object.

JSON.validateSchema<T>(data: JsonData, schema: Schema<T>): boolean;

Parameters:

  • data - The JSON object to validate should be a valid JSON object type of JsonData.
  • schema - The schema JSON object to validate the JSON object against should be a valid JSON object type of SchemaT.

Returns: - true if the JSON object is valid against the schema, false otherwise.

Example:

const data = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
  hobbies: ["football", "basketball", "tennis"],
};  

const schema = {
  name: { type: String, required: true },
  age: { type: Number },
  weight: { type: Number },
  height: { type: Number },
  address: {
    type: Object,
    properties: {
      city: { type: String },
      country: { type: String },
    }
  },
};

console.log(JSON.validateSchema(data, schema)); // true

query

The query method queries a JSON object by a string query

JSON.query(json: JsonObject, query: string): JsonData;

Parameters:

  • json - The JSON object to query should be a valid JSON object type of JsonObject.
  • query - The query string to query the JSON object by.

Returns: - The queried object, type of JsonData.

Example:

const json = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
  hobbies: ["football", "basketball", "tennis"],
};

console.log(JSON.query(json, "address.city")); // Marrakech

toHashmap

The toHashmap method converts a JSON object to a Hashmap object.

JSON.toHashmap(json: JsonObject): Hashmap;

Parameters:

  • json - The JSON object to convert should be a valid JSON object type of JsonObject.

Returns: - The converted object, type of Hashmap.

Example:

const json = {
  name: "John",
  age: 20,
  weight: 70,
  height: 180,
  address: {
    city: "Marrakech",
    country: "Morocco",
  },
  hobbies: ["football", "basketball", "tennis"],
};

console.log(JSON.toHashmap(json));

Output:

// Type Of Hashmap
{
  "name": "John",
  "age": 20,
  "weight": 70,
  "height": 180,
  "address": {
    "city": "Marrakech",
    "country": "Morocco"
  },
  "hobbies": ["football", "basketball", "tennis"],
}

Types

JSON

Here are the types used in the JSON module.

JsonData

The JsonData type is a type of JSON data.

type JsonData = JsonValue | JsonObject | JsonArray;

JsonValue

The JsonValue type is a type of JSON value.

type JsonValue = string | number | boolean | null;

JsonObject

The JsonObject type is a type of JSON object.

type JsonObject = { 
  [key: string]: JsonData
};

JsonArray

The JsonArray type is a type of JSON array.

type JsonArray = Array<JsonData>;

FlattenedObject

The FlattenedObject type is a type of flattened JSON object.

type FlattenedObject = { 
  [key: string]: JsonValue | JsonObject
};

Schema

The Schema type is a type of JSON Schema object.

SchemaProperty

The SchemaProperty type is a type of JSON Schema property.

type SchemaProperty = {
  type: StringConstructor | NumberConstructor | BooleanConstructor | typeof Object;
  required?: boolean;
  regex?: RegExp;
  properties?: SchemaProperty;
};

SchemaT

The SchemaT type is a type of JSON Schema.

  type Schema<T> = {[key in keyof T]: SchemaProperty | [SchemaProperty]} | [SchemaProperty] | SchemaProperty;

© HandyScript JSON 6/16/23

This Markdown documentation is detailed and extensive to use the handyscript modules to their full potential, along with their descriptions and TypeScript function signatures. The table of contents at the beginning Back To Top of the document allows easy navigation. If you have any questions or suggestions, don't hesitate to contact us at contact@handyscript.tech.

Clone this wiki locally