JFather

Boys use JSON; Men use JFather.

Overview

JFather is a JSON utility library to:

• merge deeply two JSON objects.
• extend a JSON objects with "$extends" property.
• override an array with "$foo[0]" (replace a value) or "$foo[]" (append values) properties.

import JFather from "jfather";

// Merge two objects.
const merged = JFather.merge(
  { "foo": "a", "bar": "alpha" },
  { "foo": "b", "baz": "beta" }
);
console.log(merged);
// { "foo": "b", "bar": "alpha", "baz": "beta" }

// Extend an object.
const extended = await JFather.extend({
  "$extends": "https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json#members[1]",
  "age": 34,
  "quote": "With great fist comes great KO"
});
console.log(extended);
// {
//   "name": "Madame Uppercut",
//   "age": 34,
//   "secretIdentity": "Jane Wilson",
//   "powers": [
//     "Million tonne punch",
//     "Damage resistance",
//     "Superhuman reflexes"
//   ],
//   "quote": "With great fist comes great KO"
// }

// Override arrays of an object.
const overridden = JFather.merge(
  { "foo": ["a", "alpha"] },
  { "$foo[0]": "A", "$foo[]": ["BETA"] }
);
console.log(overridden);
// {
//   "foo": ["A", "alpha", "BETA"]
// }

// Extend, merge and override an object.
const allIn = await JFather.extend({
  "$extends": "https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json#members[0]",
  "age": 27,
  "$powers[2]": "Atomic breath",
  "$powers[]": ["Matter Creation", "Reality Warping"],
  "quote": "I'm no God. I'm not even a man. I'm just Molecule Man."
});
console.log(allIn);
// {
//   "name": "Molecule Man",
//   "age": 27,
//   "secretIdentity": "Dan Jukes",
//   "powers": [
//     "Radiation resistance",
//     "Turning tiny",
//     "Atomic breath",
//     "Matter Creation",
//     "Reality Warping
//   ],
//   "quote": "I'm no God. I'm not even a man. I'm just Molecule Man."
// }

Installation

JFather is published on npm (its CDN: esm.sh, jsDelivr, UNPKG) and JSR.

// Node.js and Bun (after `npm install jfather`):
import JFather from "jfather";

// Browsers:
import JFather from "https://esm.sh/jfather@0";
import JFather from "https://cdn.jsdelivr.net/npm/jfather@0";
import JFather from "https://unpkg.com/jfather@0";

// Deno (after `deno add jsr:@regseb/jfather`):
import JFather from "jsr:@regseb/jfather";

Features

Merge

With any two variable types (except objects), merge returns the value of the child. The following example shows how to use it with numbers: the result is 2 (retrieved from the child value).

const parent = 1;
const child = 2;
console.log(JFather.merge(parent, child));
// 2

If both variables are objects, the object properties are merged one by one. In this example, the "foo" property overwrites that of the parent. The properties "bar" and "baz" are simply copied, as they are only in either the parent or the child.

const parent = { "foo": "alpha", "bar": "ALPHA" };
const child  = { "foo": "beta", "baz": "BETA" };
console.log(JFather.merge(parent, child));
// { "foo": "beta", "bar": "ALPHA", "baz": "BETA" }

Merging is done recursively. The following example shows the merging of two objects, which in turn contains the merging of the "foo" sub-objects.

const parent = {
  "foo": { "bar": 1, "baz": 2 },
  "qux": "a"
};
const child = {
  "foo": { "bar": 10, "quux": 20 },
  "corge": "b"
};
console.log(JFather.merge(parent, child));
// {
//   "foo": { "bar": 10, "baz": 2, "quux": 20 },
//   "qux": "a",
//   "corge": "b"
// }

Arrays are processed like any other type: the value of the child overrides that of the parent. For more detailed merging, see the Override chapter, which shows how to merge arrays.

const parent = { "foo": [1, 10, 11] };
const child  = { "foo": [2, 20, 22] };
console.log(JFather.merge(parent, child));
// { "foo": [2, 20, 22] }

Extend

You can extend an object using the "$extends" property, which must link to a JSON file. The remote JSON file and the current object will be merged.

In this example, the child object is empty (except for the "$extends" property). The result therefore contains the parent object.

// https://example.com/parent.json
// { "foo": 42 }

const obj = { "$extends": "https://example.com/parent.json" };
console.log(await JFather.extend(obj));
// { "foo": 42 }

As with merge, if a property is in both parent and child, the child's value is used. Otherwise, both parent and child properties are added to the result.

// https://example.com/parent.json
// { "foo": "A", "bar": "Alpha" }

const obj = {
  "$extends": "https://example.com/parent.json",
  "foo": "B",
  "baz": "Beta"
};
console.log(await JFather.extend(obj));
// { "foo": "B", "bar": "Alpha", "baz": "Beta" }

It is possible to extend a child's sub-object. In the example below, the parent is merged with the child's "bar" sub-object.

// https://example.com/parent.json
// { "foo": 42 }

const obj = {
  "bar": {
    "$extends": "https://example.com/parent.json",
    "baz": 3.14
  }
};
console.log(await JFather.extend(obj));
// {
//   "bar": { "foo": 42, "baz": 3.14 }
// }

In the parent link, you can define a path to retrieve a sub-object from the parent. The path is set in the URL hash:

• #foo: the value of the "foo" property;
• #foo.bar: the value of the "bar" sub-property in the "foo" property;
• #foo[42]: the value of the forty-third array element in the "foo" property;
• #foo[0].bar: the value of the sub-property "bar" in the first element of the array in the property "foo".

This example merges the "foo" property of the parent with the child.

// https://example.com/parent.json
// {
//   "foo": { "bar": [1, 2], "baz": "a" },
//   "qux": true
// }

const obj = { "$extends": "https://example.com/parent.json#foo" };
console.log(await JFather.extend(obj));
// { "bar": [1, 2], "baz": "a" }

Override

If an object has arrays, the merge overwrites the parent's array with the child's. With the properties "$foo[42]" and "$foo[]", you can refine the merge.

In this example, the array "foo" is not overwritten. The first value of the "foo" array is merged with the value of the child's "$foo[0]" property. And the second value of "foo" is copied into the result.

const parent = { "foo": ["a", "Alpha"] };
const child  = { "$foo[0]": "B" };
console.log(JFather.merge(parent, child));
// { "foo": ["B", "Alpha"] }

With "$foo[]", the child's values are added to those of the parent. In the example below, the values "b" and "Beta" are added to the array of the "foo" property.

const parent = { "foo": ["a", "Alpha"] };
const child  = { "$foo[]": ["b", "Beta"] };
console.log(JFather.merge(parent, child));
// { "foo": ["a", "Alpha", "b", "Beta"] }

You can combine the two overloads to, for example:

• merge the first value of the parent's "foo" array with the value of the child's "$foo[0]" property;
• add the values "b" and "c" to the array of the sub-property "bar".

const parent = {
  "foo": [{
    "bar": ["a"]
  }]
};
const child = {
  "$foo[0]": {
    "$bar[]": ["b", "c"]
  }
};
console.log(JFather.merge(parent, child));
// {
//   "foo": [{
//     "bar": ["a", "b", "c"]
//   }]
// }

If the child overloads a property that does not exist in the parent, the overload is ignored. The overload is also ignored if the parent object is not an array. In the following example, the child has two overloads which are ignored: the overload on the property "bar" which is not an array, and the overload on "baz" which does not exist in the parent.

const parent = { "foo": ["a", "A"], "bar": 42 };
const child  = { "$bar[0]": 3.14, "$baz[]": ["beta"] };
console.log(JFather.merge(parent, child));
// { "foo": ["a", "A"], "bar": 42 }

API

• JFather.merge(parent, child)
• JFather.extend(obj, [options])
• JFather.load(url, [options])
• JFather.parse(text, [options])

JFather.merge(parent, child)

Merge and override parent with child.

• Parameters:
  • parent <any> The parent object.
  • child <any> The child object.
• Returns: <any> The merged object.

JFather.extend(obj, [options])

Extend obj, merge and override.

• Parameter:
  • obj <any> The object with any $extends properties.
  • options <Object>
    • request <Function> The function for getting a JSON object remotely. By default, the object is got with fetch() and Response.json().
• Returns: <Promise> A promise with the extended object.

JFather.load(url, [options])

Load from an url, extend, merge and override.

• Parameter:
  • url <String> | <URL> The string containing the URL of a JSON file.
  • options <Object>
    • request <Function> The function for getting a JSON object remotely. By default, the object is got with fetch() and Response.json().
• Returns: <Promise> A promise with the loaded object.

JFather.parse(text, [options])

Parse a text, extend, merge and override.

• Parameter:
  • text <String> The string containing a JSON object.
  • options <Object>
    • request <Function> The function for getting a JSON object remotely. By default, the object is got with fetch() and Response.json().
• Returns: <Promise> A promise with the parsed object.