Skip to main content

JFather

npm build coverage semver

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()

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);
  • Parameter:
    • obj: The object with any $extends properties.
  • Returns: A promise with the extended object.

load()

Load from a url, extend, merge and override.

JFather.load(url);
  • Parameter:
    • url: The string containing the URL of a JSON file.
  • Returns: A promise with the loaded object.

parse()

Parse a text, extend, merge and override.

JFather.parse(text);
  • Parameter:
    • text: The string containing a JSON object.
  • Returns: A promise with the parsed object.