JFather

Boys use JSON; Men use JFather.

Overview

JFather is a utility library to merge, extend and override JSON objects.

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 an object.
const overridden = await 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 Deno.

// 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:
import JFather from "https://deno.land/x/jfather/mod.js";

Features

Merge

parent	child	JFather.merge(parent, child)
1	2	2
{ "foo": "alpha", "bar": "ALPHA" }	{ "foo": "beta", "baz": "BETA" }	{ "foo": "beta", "bar": "ALPHA", "baz": "BETA" }
{ "foo": [1, 10, 11] }	{ "foo": [2, 20, 22] }	{ "foo": [2, 20, 22] }

Extend

https://foo.bar/parent.json	child	await JFather.extend(child)
{ "baz": "qux" }	{ "$extends": "https://foo.bar/parent.json" }	{ "baz": "qux" }
{ "baz": "qux" }	{ "$extends": "https://foo.bar/parent.json", "baz": "quux" }	{ "baz": "quux" }
{ "baz": "qux" }	{ "$extends": "https://foo.bar/parent.json", "quux": "corge" }	{ "baz": "qux", "quux": "corge" }
{ "baz": "qux" }	{ "quux": { "$extends": "https://foo.bar/parent.json", "corge": "grault" } }	{ "quux": { "baz": "qux", "corge": "grault" } }
{ "baz": { "qux": [1, 2], "quux": "a" }, "corge": true }	{ "$extends": "https://foo.bar/parent.json#baz" }	{ "qux": [1, 2], "quux": "a" }

Override

parent	child	JFather.merge(parent, child)
{ "foo": ["a", "Alpha"] }	{ "$foo[]": ["b", "Beta"] }	{ "foo": ["a", "Alpha", "b", "Beta"] }
{ "foo": ["a", "Alpha"] }	{ "$foo[0]": "A" }	{ "foo": ["A", "Alpha"] }
{ "foo": [{ "bar": ["a"] }] }	{ "$foo[0]": { "$bar[]": ["b", "c"] } }	{ "foo": [{ "bar": ["a", "b", "c"] }] }

API

• merge()
• extend()
• load()
• parse()

merge()

Merge and override parent with child.

JFather.merge(parent, child);

• Parameters:
  • parent: The parent object.
  • child: The child object.
• Returns: The merged object.

extend()

Extend obj, merge and override.

JFather.extend(obj, [options]);

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

load()

Load from a url, extend, merge and override.

JFather.load(url, [options]);

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

parse()

Parse a text, extend, merge and override.

JFather.parse(text, [options]);

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