jfather 0.2.0 → 0.3.0

package/README.md

@@ -15,9 +15,10 @@
 ## Overview
 
 JFather is a utility library to **merge**, **extend** and **override**
-[JSON](https://www.json.org/json-fr.html "JavaScript Object Notation") objects.
+[JSON](https://www.json.org/json-en.html "JavaScript Object Notation") objects.
 
-```JavaScript
+<!-- prettier-ignore-start -->
+```javascript
 import JFather from "jfather";
 
 // Merge two objects.
@@ -80,6 +81,7 @@ console.log(allIn);
 //   "quote": "I'm no God. I'm not even a man. I'm just Molecule Man."
 // }
 ```
+<!-- prettier-ignore-end -->
 
 ## Installation
 
@@ -89,7 +91,7 @@ JFather is published on [npm][link-npm] (its CDN:
 [UNPKG](https://unpkg.com/browse/jfather/)) and
 [Deno](https://deno.land/x/jfather).
 
-```JavaScript
+```javascript
 // Node.js and Bun (after `npm install jfather`):
 import JFather from "jfather";
 
@@ -114,33 +116,33 @@ import JFather from "https://deno.land/x/jfather/mod.js";
     <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>
+    <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>{
+    <td><pre lang="json"><code>{
   "foo": "alpha",
   "bar": "ALPHA"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": "beta",
   "baz": "BETA"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": "beta",
   "bar": "ALPHA",
   "baz": "BETA"
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": [1, 10, 11]
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": [2, 20, 22]
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": [2, 20, 22]
 }</code></pre></td>
   </tr>
@@ -157,52 +159,52 @@ import JFather from "https://deno.land/x/jfather/mod.js";
     <th><code>await JFather.extend(child)</code></th>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "qux"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "$extends": "https://foo.bar/parent.json"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "qux"
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "qux"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "$extends": "https://foo.bar/parent.json",
   "baz": "quux"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "quux"
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "qux"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "$extends": "https://foo.bar/parent.json",
   "quux": "corge"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "qux",
   "quux": "corge"
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": "qux"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "quux": {
     "$extends": "https://foo.bar/parent.json",
     "corge": "grault"
   }
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "quux": {
     "baz": "qux",
     "corge": "grault"
@@ -210,17 +212,17 @@ import JFather from "https://deno.land/x/jfather/mod.js";
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "baz": {
     "qux": [1, 2],
     "quux": "a"
   },
   "corge": true
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "$extends": "https://foo.bar/parent.json#baz"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "qux": [1, 2],
   "quux": "a"
 }</code></pre></td>
@@ -238,36 +240,42 @@ import JFather from "https://deno.land/x/jfather/mod.js";
     <th><code>JFather.merge(parent, child)</code></th>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": ["a", "Alpha"]
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "$foo[]": ["b", "Beta"]
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": ["a", "Alpha", "b", "Beta"]
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": ["a", "Alpha"]
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "$foo[0]": "A"
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
+    <td><pre lang="json"><code>{
   "foo": ["A", "Alpha"]
 }</code></pre></td>
   </tr>
   <tr>
-    <td><pre lang="JSON"><code>{
-  "foo": [{ "bar": ["a"] }]
+    <td><pre lang="json"><code>{
+  "foo": [{
+    "bar": ["a"]
+  }]
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
-  "$foo[0]": { "$bar[]": ["b", "c"] }
+    <td><pre lang="json"><code>{
+  "$foo[0]": {
+    "$bar[]": ["b", "c"]
+  }
 }</code></pre></td>
-    <td><pre lang="JSON"><code>{
-  "foo": [{ "bar": ["a", "b", "c"] }]
+    <td><pre lang="json"><code>{
+  "foo": [{
+    "bar": ["a", "b", "c"]
+  }]
 }</code></pre></td>
   </tr>
 </table>
@@ -284,7 +292,7 @@ import JFather from "https://deno.land/x/jfather/mod.js";
 
 Merge and override `parent` with `child`.
 
-```JavaScript
+```javascript
 JFather.merge(parent, child);
 ```
 
@@ -297,41 +305,56 @@ JFather.merge(parent, child);
 
 Extend `obj`, merge and override.
 
-```JavaScript
-JFather.extend(obj);
+```javascript
+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()`](https://developer.mozilla.org/Web/API/fetch) and
+      [`Response.json()`](https://developer.mozilla.org/Web/API/Response/json).
 - Returns: A promise with the extended object.
 
 ### `load()`
 
 Load from a `url`, extend, merge and override.
 
-```JavaScript
-JFather.load(url);
+```javascript
+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()`](https://developer.mozilla.org/Web/API/fetch) and
+      [`Response.json()`](https://developer.mozilla.org/Web/API/Response/json).
 - Returns: A promise with the loaded object.
 
 ### `parse()`
 
 Parse a `text`, extend, merge and override.
 
-```JavaScript
-JFather.parse(text);
+```javascript
+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()`](https://developer.mozilla.org/Web/API/fetch) and
+      [`Response.json()`](https://developer.mozilla.org/Web/API/Response/json).
 - 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
-[img-coverage]: https://img.shields.io/endpoint?label=coverage&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fregseb%2Fjfather%2Fmain&logo=stryker&logoColor=whitesmoke
+[img-coverage]: https://img.shields.io/endpoint?label=coverage&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fregseb%2Fjfather%2Fmain
 [img-semver]: https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&logoColor=whitesmoke
 [link-npm]: https://www.npmjs.com/package/jfather
 [link-build]: https://github.com/regseb/jfather/actions/workflows/ci.yml?query=branch%3Amain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jfather",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "JSON with merge, extend and override.",
   "keywords": [
     "jfather",
@@ -18,7 +18,10 @@
   },
   "license": "MIT",
   "author": "Sébastien Règne <regseb@gmail.com> (https://github.com/regseb)",
-  "funding": "https://www.paypal.me/sebastienregne",
+  "funding": [
+    "https://buymeacoffee.com/regseb",
+    "https://www.paypal.me/sebastienregne"
+  ],
   "files": [
     "./src/",
     "./types/"
@@ -47,31 +50,32 @@
   },
   "devDependencies": {
     "@prantlf/jsonlint": "14.0.3",
-    "@prettier/plugin-xml": "3.3.1",
+    "@prettier/plugin-xml": "3.4.1",
     "@stryker-mutator/core": "8.2.6",
     "@stryker-mutator/mocha-runner": "8.2.6",
     "@types/mocha": "10.0.6",
-    "@types/node": "20.11.24",
+    "@types/node": "20.12.12",
     "@types/sinon": "17.0.3",
     "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.2.0",
-    "eslint-plugin-mocha": "10.3.0",
-    "eslint-plugin-n": "16.6.2",
+    "eslint-plugin-jsdoc": "48.2.5",
+    "eslint-plugin-mocha": "10.4.3",
+    "eslint-plugin-n": "17.7.0",
     "eslint-plugin-no-unsanitized": "4.0.2",
     "eslint-plugin-promise": "6.1.1",
-    "eslint-plugin-regexp": "2.2.0",
-    "eslint-plugin-unicorn": "51.0.1",
-    "markdownlint": "0.33.0",
-    "metalint": "0.15.0",
-    "mocha": "10.3.0",
+    "eslint-plugin-regexp": "2.6.0",
+    "eslint-plugin-unicorn": "53.0.0",
+    "markdownlint": "0.34.0",
+    "metalint": "0.17.0",
+    "mocha": "10.4.0",
     "npm-package-json-lint": "7.1.0",
     "prettier": "3.2.5",
-    "sinon": "17.0.1",
-    "typedoc": "0.25.10",
-    "typescript": "5.3.3",
+    "publint": "0.2.8",
+    "sinon": "18.0.0",
+    "typedoc": "0.25.13",
+    "typescript": "5.4.5",
     "yaml-lint": "1.7.0"
   },
   "engines": {

package/src/jfather.js

@@ -4,6 +4,16 @@
  * @author Sébastien Règne
  */
 
+/**
+ * Les options des fonctions de JFather.
+ *
+ * @typedef {Object} Options
+ * @prop {Function} [request] La fonction pour récupérer un objet JSON à
+ *                            distance. Par défaut, l'objet est récupéré avec
+ *                            <code>fetch()</code> et
+ *                            <code>Response.prototype.json()</code>
+ */
+
 /**
  * Exécute une fonction sur un objet et tous ses sous-objets (en partant des
  * objets les plus profonds).
@@ -163,48 +173,57 @@ export const merge = function (parent, child) {
 /**
  * Étendre un objet JSON en utilisant les propriétés <code>"$extends"</code>.
  *
- * @param {Record<string, any>} obj L'objet qui sera étendu.
+ * @param {Record<string, any>} obj       L'objet qui sera étendu.
+ * @param {Options}             [options] Les options.
  * @returns {Promise<Record<string, any>>} Une promesse contenant l'objet
  *                                         étendu.
  */
-export const inherit = async function (obj) {
+export const inherit = async function (obj, options) {
     if (undefined === obj.$extends) {
         return obj;
     }
 
     // eslint-disable-next-line no-use-before-define
-    return merge(await load(obj.$extends), obj);
+    return merge(await load(obj.$extends, options), obj);
 };
 
 /**
  * Étendre un objet récursivement.
  *
- * @param {any} obj L'objet qui sera étendu.
+ * @param {any}     obj       L'objet qui sera étendu.
+ * @param {Options} [options] Les options.
  * @returns {Promise<any>} Une promesse contenant l'objet étendu.
  */
-export const extend = function (obj) {
-    return walkAsync(obj, inherit);
+export const extend = function (obj, options) {
+    return walkAsync(obj, (/** @type {any} */ v) => inherit(v, options));
 };
 
 /**
  * Charge un objet JSON depuis une URL.
  *
- * @param {string} url L'URL du fichier JSON.
+ * @param {string}  url       L'URL du fichier JSON.
+ * @param {Options} [options] Les options.
  * @returns {Promise<any>} Une promesse contenant l'objet.
  */
-export const load = async function (url) {
-    const response = await fetch(url);
-    const json = await response.json();
+export const load = async function (url, options) {
+    let json;
+    if (undefined === options?.request) {
+        const response = await fetch(url);
+        json = await response.json();
+    } else {
+        json = await options.request(url);
+    }
     // Enlever le "#" dans le hash de l'URL.
-    return await extend(query(json, new URL(url).hash.slice(1)));
+    return await extend(query(json, new URL(url).hash.slice(1)), options);
 };
 
 /**
  * Parse une chaine de caractères.
  *
- * @param {string} text La chaine de caractères qui sera parsée.
+ * @param {string}  text      La chaine de caractères qui sera parsée.
+ * @param {Options} [options] Les options.
  * @returns {Promise<any>} L'objet.
  */
-export const parse = function (text) {
-    return extend(JSON.parse(text));
+export const parse = function (text, options) {
+    return extend(JSON.parse(text), options);
 };

package/types/jfather.d.ts

@@ -3,7 +3,19 @@ export function walkAsync(obj: any, fn: Function): Promise<any>;
 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 extend(obj: any): Promise<any>;
-export function load(url: string): Promise<any>;
-export function parse(text: string): Promise<any>;
+export function inherit(obj: Record<string, any>, options?: Options): Promise<Record<string, any>>;
+export function extend(obj: any, options?: Options): Promise<any>;
+export function load(url: string, options?: Options): Promise<any>;
+export function parse(text: string, options?: Options): Promise<any>;
+/**
+ * Les options des fonctions de JFather.
+ */
+export type Options = {
+    /**
+     * La fonction pour récupérer un objet JSON à
+     *  distance. Par défaut, l'objet est récupéré avec
+     *  <code>fetch()</code> et
+     *  <code>Response.prototype.json()</code>
+     */
+    request?: Function;
+};