jfather 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2024 Sébastien Règne
+Copyright (c) 2024 Sébastien Règne
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -10,100 +10,324 @@
 [![coverage][img-coverage]][link-coverage]
 [![semver][img-semver]][link-semver]
 
-> Boys use JSON; Men use JFather.
+> _Boys use JSON; Men use JFather._
 
 ## Overview
 
-**JFather** is
-[JSON](https://www.json.org/json-fr.html "JavaScript Object Notation") with
-features to merge, extend and override JSON objects.
+JFather is a utility library to **merge**, **extend** and **override**
+[JSON](https://www.json.org/json-fr.html "JavaScript Object Notation") objects.
 
 ```JavaScript
 import JFather from "jfather";
 
+// Merge two objects.
 const merged = JFather.merge(
-    { foo: "a", bar: "alpha" },
-    { foo: "b", baz: "beta" },
+  { "foo": "a", "bar": "alpha" },
+  { "foo": "b", "baz": "beta" }
 );
-
 console.log(merged);
-// { foo: "b", bar: "alpha", baz: "beta" }
-```
-
-## Install
+// { "foo": "b", "bar": "alpha", "baz": "beta" }
 
-### Node.js
+// 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"
+// }
 
-JFather is published on [npm][link-npm].
+// Override an object.
+const overridden = await JFather.merge(
+  { "foo": ["a", "alpha"] },
+  { "$foo[0]": "A", "$foo[]": ["BETA"] }
+);
+console.log(overridden);
+// {
+//   "foo": ["A", "alpha", "BETA"]
+// }
 
-```JavaScript
-import JFather from "jfather";
+// 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."
+// }
 ```
 
-### Deno
-
-The library is available in [Deno](https://deno.land/x/jfather).
+## Installation
 
-```JavaScript
-import JFather from "https://deno.land/x/jfather/mod.js";
-```
-
-### Browsers
-
-It can also be accessed directly from the CDN
-[esm.sh](https://esm.sh/jfather) (ou
+JFather is published on [npm][link-npm] (its CDN:
+[esm.sh](https://esm.sh/jfather),
 [jsDelivr](https://www.jsdelivr.com/package/npm/jfather),
-[UNPKG](https://unpkg.com/browse/jfather/)) :
+[UNPKG](https://unpkg.com/browse/jfather/)) and
+[Deno](https://deno.land/x/jfather).
 
 ```JavaScript
+// 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";
+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";
 ```
 
-## API
+## Features
 
-- [`merge()`](#merge)
-- [`load()`](#load)
-- [`parse()`](#parse)
+### Merge
 
-### merge()
+<!-- markdownlint-disable no-inline-html -->
+<table>
+  <tr>
+    <th><code>parent</code></th>
+    <th><code>child</code></th>
+    <th><code>JFather.merge(parent, child)</code></th>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>1</code></pre></td>
+    <td><pre lang="JSON"><code>2</code></pre></td>
+    <td><pre lang="JSON"><code>2</code></pre></td>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "foo": "alpha",
+  "bar": "ALPHA"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": "beta",
+  "baz": "BETA"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": "beta",
+  "bar": "ALPHA",
+  "baz": "BETA"
+}</code></pre></td>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "foo": [1, 10, 11]
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": [2, 20, 22]
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": [2, 20, 22]
+}</code></pre></td>
+  </tr>
+</table>
+<!-- markdownlint-enable no-inline-html -->
 
-Merge two variables.
+### Extend
 
 <!-- markdownlint-disable no-inline-html -->
 <table>
   <tr>
-    <th><code>a</code></th>
-    <th><code>b</code></th>
-    <th><code>JFather.merge(a, b)</code></th>
+    <th><code>https://foo.bar/parent.json</code></th>
+    <th><code>child</code></th>
+    <th><code>await JFather.extend(child)</code></th>
   </tr>
   <tr>
-    <td><code>1</code></td>
-    <td><code>2</code></td>
-    <td><code>2</code></td>
+    <td><pre lang="JSON"><code>{
+  "baz": "qux"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$extends": "https://foo.bar/parent.json"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "baz": "qux"
+}</code></pre></td>
   </tr>
   <tr>
-    <td><code>{ foo: "alpha", bar: "ALPHA" }</code></td>
-    <td><code>{ foo: "beta", baz: "BETA" }</code></td>
-    <td><code>{ foo: "beta", bar: "ALPHA", baz: "BETA" }</code></td>
+    <td><pre lang="JSON"><code>{
+  "baz": "qux"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$extends": "https://foo.bar/parent.json",
+  "baz": "quux"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "baz": "quux"
+}</code></pre></td>
   </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "baz": "qux"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$extends": "https://foo.bar/parent.json",
+  "quux": "corge"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "baz": "qux",
+  "quux": "corge"
+}</code></pre></td>
   </tr>
   <tr>
-    <td><code>{ foo: [1, 10, 11] }</code></td>
-    <td><code>{ foo: [2, 20, 22] }</code></td>
-    <td><code>{ foo: [2, 20, 22] }</code></td>
+    <td><pre lang="JSON"><code>{
+  "baz": "qux"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "quux": {
+    "$extends": "https://foo.bar/parent.json",
+    "corge": "grault"
+  }
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "quux": {
+    "baz": "qux",
+    "corge": "grault"
+  }
+}</code></pre></td>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "baz": {
+    "qux": [1, 2],
+    "quux": "a"
+  },
+  "corge": true
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$extends": "https://foo.bar/parent.json#baz"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "qux": [1, 2],
+  "quux": "a"
+}</code></pre></td>
   </tr>
 </table>
 <!-- markdownlint-enable no-inline-html -->
 
-### load()
+### Override
 
-Load an object from an URL.
+<!-- markdownlint-disable no-inline-html -->
+<table>
+  <tr>
+    <th><code>parent</code></th>
+    <th><code>child</code></th>
+    <th><code>JFather.merge(parent, child)</code></th>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "foo": ["a", "Alpha"]
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$foo[]": ["b", "Beta"]
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": ["a", "Alpha", "b", "Beta"]
+}</code></pre></td>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "foo": ["a", "Alpha"]
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$foo[0]": "A"
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": ["A", "Alpha"]
+}</code></pre></td>
+  </tr>
+  <tr>
+    <td><pre lang="JSON"><code>{
+  "foo": [{ "bar": ["a"] }]
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "$foo[0]": { "$bar[]": ["b", "c"] }
+}</code></pre></td>
+    <td><pre lang="JSON"><code>{
+  "foo": [{ "bar": ["a", "b", "c"] }]
+}</code></pre></td>
+  </tr>
+</table>
+<!-- markdownlint-enable no-inline-html -->
 
-### parse()
+## API
+
+- [`merge()`](#merge)
+- [`extend()`](#extend)
+- [`load()`](#load)
+- [`parse()`](#parse)
+
+### `merge()`
+
+Merge and override `parent` with `child`.
+
+```JavaScript
+JFather.merge(parent, child);
+```
+
+- Parameters:
+  - `parent`: The parent object.
+  - `child`: The child object.
+- Returns: The merged object.
+
+### `extend()`
+
+Extend `obj`, merge and override.
+
+```JavaScript
+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.
+
+```JavaScript
+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.
+
+```JavaScript
+JFather.parse(text);
+```
 
-Parse a string.
+- Parameter:
+  - `text`: The string containing a JSON object.
+- Returns: A promise with the parsed object.
 
 [img-npm]: https://img.shields.io/npm/dm/jfather?label=npm&logo=npm&logoColor=whitesmoke
 [img-build]: https://img.shields.io/github/actions/workflow/status/regseb/jfather/ci.yml?branch=main&logo=github&logoColor=whitesmoke

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jfather",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "JSON with merge, extend and override.",
   "keywords": [
     "jfather",
@@ -47,18 +47,18 @@
   },
   "devDependencies": {
     "@prantlf/jsonlint": "14.0.3",
-    "@prettier/plugin-xml": "3.3.0",
-    "@stryker-mutator/core": "8.2.3",
-    "@stryker-mutator/mocha-runner": "8.2.3",
+    "@prettier/plugin-xml": "3.3.1",
+    "@stryker-mutator/core": "8.2.6",
+    "@stryker-mutator/mocha-runner": "8.2.6",
     "@types/mocha": "10.0.6",
-    "@types/node": "20.11.17",
+    "@types/node": "20.11.24",
     "@types/sinon": "17.0.3",
-    "eslint": "8.56.0",
+    "eslint": "8.57.0",
     "eslint-plugin-array-func": "4.0.0",
     "eslint-plugin-eslint-comments": "3.2.0",
     "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-jsdoc": "48.0.6",
-    "eslint-plugin-mocha": "10.2.0",
+    "eslint-plugin-jsdoc": "48.2.0",
+    "eslint-plugin-mocha": "10.3.0",
     "eslint-plugin-n": "16.6.2",
     "eslint-plugin-no-unsanitized": "4.0.2",
     "eslint-plugin-promise": "6.1.1",
@@ -70,7 +70,7 @@
     "npm-package-json-lint": "7.1.0",
     "prettier": "3.2.5",
     "sinon": "17.0.1",
-    "typedoc": "0.25.8",
+    "typedoc": "0.25.10",
     "typescript": "5.3.3",
     "yaml-lint": "1.7.0"
   },

package/src/index.js

@@ -4,6 +4,6 @@
  * @author Sébastien Règne
  */
 
-import { load, merge, parse } from "./jfather.js";
+import { extend, load, merge, parse } from "./jfather.js";
 
-export default { load, merge, parse };
+export default { extend, load, merge, parse };

package/src/jfather.js

@@ -38,7 +38,7 @@ export const walk = function (obj, fn) {
  */
 export const walkAsync = async function (obj, fn) {
     if (Object === obj?.constructor) {
-        return fn(
+        return await fn(
             Object.fromEntries(
                 await Promise.all(
                     Object.entries(obj).map(async ([key, value]) => [
@@ -51,7 +51,7 @@ export const walkAsync = async function (obj, fn) {
     }
 
     if (Array.isArray(obj)) {
-        return Promise.all(obj.map((v) => walkAsync(v, fn)));
+        return await Promise.all(obj.map((v) => walkAsync(v, fn)));
     }
 
     return obj;
@@ -76,8 +76,16 @@ export const clone = function (obj) {
  * @throws {TypeError} Si le chemin est invalide.
  */
 export const query = function (obj, chain) {
+    if ("" === chain) {
+        return obj;
+    }
+
     const re = /^\.(?<prop>\w+)|^\[(?<index>\d+)\]/u;
-    const sub = { obj, chain };
+    const sub = {
+        obj,
+        // Préfixer le chemin avec un point si nécessaire.
+        chain: /^[.[]/u.test(chain) ? chain : "." + chain,
+    };
     while (0 !== sub.chain.length) {
         const result = re.exec(sub.chain);
         if (undefined !== result?.groups?.prop) {
@@ -105,7 +113,7 @@ export const merge = function (parent, child) {
         return clone(child);
     }
 
-    const overrode = /** @type {Record<string, any>} */ ({});
+    const overridden = /** @type {Record<string, any>} */ ({});
     for (const key of new Set([
         ...Object.keys(parent),
         ...Object.keys(child),
@@ -118,18 +126,18 @@ export const merge = function (parent, child) {
         // Si la propriété est dans les deux objets : fusionner les deux
         // valeurs.
         if (key in parent && key in child) {
-            overrode[key] = merge(parent[key], child[key]);
+            overridden[key] = merge(parent[key], child[key]);
             // Si la propriété est seulement dans l'objet parent.
         } else if (key in parent) {
-            overrode[key] = clone(parent[key]);
+            overridden[key] = clone(parent[key]);
             // Si la propriété est seulement dans l'objet enfant.
         } else {
-            overrode[key] = clone(child[key]);
+            overridden[key] = clone(child[key]);
         }
 
         // Si la valeur est un tableau : chercher si l'objet enfant a des
         // surcharges d'éléments.
-        if (Array.isArray(overrode[key])) {
+        if (Array.isArray(overridden[key])) {
             const overelemRegex = new RegExp(
                 `^\\$${key}\\[(?<index>\\d*)\\]$`,
                 "u",
@@ -139,28 +147,28 @@ export const merge = function (parent, child) {
                 .filter(([i]) => undefined !== i);
             for (const [index, value] of overelems) {
                 if ("" === index) {
-                    overrode[key].push(clone(value));
+                    overridden[key].push(...clone(value));
                 } else {
-                    overrode[key][Number(index)] = merge(
-                        overrode[key][Number(index)],
+                    overridden[key][Number(index)] = merge(
+                        overridden[key][Number(index)],
                         value,
                     );
                 }
             }
         }
     }
-    return overrode;
+    return overridden;
 };
 
 /**
- * Étendre un objet JSON en utilisant les propriétes <code>"$extends"</code>.
+ * Étendre un objet JSON en utilisant les propriétés <code>"$extends"</code>.
  *
  * @param {Record<string, any>} obj L'objet qui sera étendu.
  * @returns {Promise<Record<string, any>>} Une promesse contenant l'objet
  *                                         étendu.
  */
 export const inherit = async function (obj) {
-    if (undefined === obj?.$extends) {
+    if (undefined === obj.$extends) {
         return obj;
     }
 
@@ -174,7 +182,7 @@ export const inherit = async function (obj) {
  * @param {any} obj L'objet qui sera étendu.
  * @returns {Promise<any>} Une promesse contenant l'objet étendu.
  */
-export const transform = function (obj) {
+export const extend = function (obj) {
     return walkAsync(obj, inherit);
 };
 
@@ -187,15 +195,16 @@ export const transform = function (obj) {
 export const load = async function (url) {
     const response = await fetch(url);
     const json = await response.json();
-    return transform(query(json, new URL(url).hash.replace(/^#/u, ".")));
+    // Enlever le "#" dans le hash de l'URL.
+    return await extend(query(json, new URL(url).hash.slice(1)));
 };
 
 /**
  * Parse une chaine de caractères.
  *
  * @param {string} text La chaine de caractères qui sera parsée.
- * @returns {any} L'objet.
+ * @returns {Promise<any>} L'objet.
  */
 export const parse = function (text) {
-    return transform(JSON.parse(text));
+    return extend(JSON.parse(text));
 };

package/types/index.d.ts

@@ -1,9 +1,11 @@
 declare namespace _default {
+    export { extend };
     export { load };
     export { merge };
     export { parse };
 }
 export default _default;
+import { extend } from "./jfather.js";
 import { load } from "./jfather.js";
 import { merge } from "./jfather.js";
 import { parse } from "./jfather.js";

package/types/jfather.d.ts

@@ -4,6 +4,6 @@ export function clone(obj: any): any;
 export function query(obj: Record<string, any>, chain: string): any;
 export function merge(parent: any, child: any): any;
 export function inherit(obj: Record<string, any>): Promise<Record<string, any>>;
-export function transform(obj: any): Promise<any>;
+export function extend(obj: any): Promise<any>;
 export function load(url: string): Promise<any>;
-export function parse(text: string): any;
+export function parse(text: string): Promise<any>;