jfather 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# JFather
+
+<!-- Utiliser du HTML (avec l'attribut "align" obsolète) pour faire flotter
+     l'image à droite. -->
+<!-- markdownlint-disable-next-line no-inline-html-->
+<img src="asset/logo.svg" align="right" alt="">
+
+[![npm][img-npm]][link-npm]
+[![build][img-build]][link-build]
+[![coverage][img-coverage]][link-coverage]
+[![semver][img-semver]][link-semver]
+
+> 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.
+
+```JavaScript
+import JFather from "jfather";
+
+const merged = JFather.merge(
+    { foo: "a", bar: "alpha" },
+    { foo: "b", baz: "beta" },
+);
+
+console.log(merged);
+// { foo: "b", bar: "alpha", baz: "beta" }
+```
+
+## Install
+
+### Node.js
+
+JFather is published on [npm][link-npm].
+
+```JavaScript
+import JFather from "jfather";
+```
+
+### Deno
+
+The library is available in [Deno](https://deno.land/x/jfather).
+
+```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
+[jsDelivr](https://www.jsdelivr.com/package/npm/jfather),
+[UNPKG](https://unpkg.com/browse/jfather/)) :
+
+```JavaScript
+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";
+```
+
+## API
+
+- [`merge()`](#merge)
+- [`load()`](#load)
+- [`parse()`](#parse)
+
+### merge()
+
+Merge two variables.
+
+<!-- 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>
+  </tr>
+  <tr>
+    <td><code>1</code></td>
+    <td><code>2</code></td>
+    <td><code>2</code></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>
+  </tr>
+  </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>
+  </tr>
+</table>
+<!-- markdownlint-enable no-inline-html -->
+
+### load()
+
+Load an object from an URL.
+
+### parse()
+
+Parse a string.
+
+[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-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
+[link-coverage]: https://dashboard.stryker-mutator.io/reports/github.com/regseb/jfather/main
+[link-semver]: https://semver.org/spec/v2.0.0.html "Semantic Versioning 2.0.0"

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "jfather",
+  "version": "0.1.0",
+  "description": "JSON with merge, extend and override.",
+  "keywords": [
+    "jfather",
+    "json",
+    "merge",
+    "extend",
+    "override",
+    "front-end",
+    "backend"
+  ],
+  "homepage": "https://github.com/regseb/jfather#readme",
+  "bugs": {
+    "url": "https://github.com/regseb/jfather/issues",
+    "email": "regseb@gmail.com"
+  },
+  "license": "MIT",
+  "author": "Sébastien Règne <regseb@gmail.com> (https://github.com/regseb)",
+  "funding": "https://www.paypal.me/sebastienregne",
+  "files": [
+    "./src/",
+    "./types/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "repository": "regseb/jfather",
+  "type": "module",
+  "scripts": {
+    "lint": "metalint",
+    "lint:fix": "metalint --fix",
+    "lint:types": "tsc --project .tsconfig_lint.json",
+    "test": "npm run test:coverage",
+    "test:unit": "mocha --config test/mocharc.json",
+    "test:coverage": "stryker run",
+    "jsdocs": "typedoc --tsconfig .tsconfig_jsdocs.json",
+    "prepare": "tsc --project .tsconfig_types.json",
+    "clean": "node .script/clean.js"
+  },
+  "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",
+    "@types/mocha": "10.0.6",
+    "@types/node": "20.11.17",
+    "@types/sinon": "17.0.3",
+    "eslint": "8.56.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-n": "16.6.2",
+    "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",
+    "npm-package-json-lint": "7.1.0",
+    "prettier": "3.2.5",
+    "sinon": "17.0.1",
+    "typedoc": "0.25.8",
+    "typescript": "5.3.3",
+    "yaml-lint": "1.7.0"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,9 @@
+/**
+ * @module jfather
+ * @license MIT
+ * @author Sébastien Règne
+ */
+
+import { load, merge, parse } from "./jfather.js";
+
+export default { load, merge, parse };

package/src/jfather.js

@@ -0,0 +1,201 @@
+/**
+ * @module
+ * @license MIT
+ * @author Sébastien Règne
+ */
+
+/**
+ * Exécute une fonction sur un objet et tous ses sous-objets (en partant des
+ * objets les plus profonds).
+ *
+ * @param {any}      obj Une variable quelconque.
+ * @param {Function} fn  La fonction appliquée sur tous les objets.
+ * @returns {any} Le retour de la fonction.
+ */
+export const walk = function (obj, fn) {
+    if (Object === obj?.constructor) {
+        return fn(
+            Object.fromEntries(
+                Object.entries(obj).map(([k, v]) => [k, walk(v, fn)]),
+            ),
+        );
+    }
+
+    if (Array.isArray(obj)) {
+        return obj.map((v) => walk(v, fn));
+    }
+
+    return obj;
+};
+
+/**
+ * Exécute une fonction asynchrone sur un objet et tous ses sous-objets (en
+ * partant des objets les plus profonds).
+ *
+ * @param {any}      obj Une variable quelconque.
+ * @param {Function} fn  La fonction asynchrone appliquée sur tous les objets.
+ * @returns {Promise<any>} Une promesse contenant le retour de la fonction.
+ */
+export const walkAsync = async function (obj, fn) {
+    if (Object === obj?.constructor) {
+        return fn(
+            Object.fromEntries(
+                await Promise.all(
+                    Object.entries(obj).map(async ([key, value]) => [
+                        key,
+                        await walkAsync(value, fn),
+                    ]),
+                ),
+            ),
+        );
+    }
+
+    if (Array.isArray(obj)) {
+        return Promise.all(obj.map((v) => walkAsync(v, fn)));
+    }
+
+    return obj;
+};
+
+/**
+ * Clone récursivement un objet.
+ *
+ * @param {any} obj Une variable quelconque.
+ * @returns {any} Le clone de la variable d'entrée.
+ */
+export const clone = function (obj) {
+    return walk(obj, (/** @type {any} */ v) => v);
+};
+
+/**
+ * Extrait un élément d'un objet.
+ *
+ * @param {Record<string, any>} obj   L'objet où sera extrait l'élément.
+ * @param {string}              chain Le chemin de l'élément.
+ * @returns {any} L'élément extrait.
+ * @throws {TypeError} Si le chemin est invalide.
+ */
+export const query = function (obj, chain) {
+    const re = /^\.(?<prop>\w+)|^\[(?<index>\d+)\]/u;
+    const sub = { obj, chain };
+    while (0 !== sub.chain.length) {
+        const result = re.exec(sub.chain);
+        if (undefined !== result?.groups?.prop) {
+            sub.obj = sub.obj[result.groups.prop];
+            // eslint-disable-next-line no-negated-condition
+        } else if (undefined !== result?.groups?.index) {
+            sub.obj = sub.obj[Number(result.groups.index)];
+        } else {
+            throw new TypeError(`Invalid chain: ${chain}`);
+        }
+        sub.chain = sub.chain.slice(result[0].length);
+    }
+    return sub.obj;
+};
+
+/**
+ * Fusionne deux objets récursivement.
+ *
+ * @param {any} parent L'objet parent.
+ * @param {any} child  L'objet enfant.
+ * @returns {any} La fusion des deux objets.
+ */
+export const merge = function (parent, child) {
+    if (Object !== parent?.constructor || Object !== child?.constructor) {
+        return clone(child);
+    }
+
+    const overrode = /** @type {Record<string, any>} */ ({});
+    for (const key of new Set([
+        ...Object.keys(parent),
+        ...Object.keys(child),
+    ])) {
+        // Ne pas copier les surcharges d'éléments.
+        if (key.startsWith("$")) {
+            continue;
+        }
+
+        // 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]);
+            // Si la propriété est seulement dans l'objet parent.
+        } else if (key in parent) {
+            overrode[key] = clone(parent[key]);
+            // Si la propriété est seulement dans l'objet enfant.
+        } else {
+            overrode[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])) {
+            const overelemRegex = new RegExp(
+                `^\\$${key}\\[(?<index>\\d*)\\]$`,
+                "u",
+            );
+            const overelems = Object.entries(child)
+                .map(([k, v]) => [overelemRegex.exec(k)?.groups?.index, v])
+                .filter(([i]) => undefined !== i);
+            for (const [index, value] of overelems) {
+                if ("" === index) {
+                    overrode[key].push(clone(value));
+                } else {
+                    overrode[key][Number(index)] = merge(
+                        overrode[key][Number(index)],
+                        value,
+                    );
+                }
+            }
+        }
+    }
+    return overrode;
+};
+
+/**
+ * Étendre un objet JSON en utilisant les propriétes <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) {
+        return obj;
+    }
+
+    // eslint-disable-next-line no-use-before-define
+    return merge(await load(obj.$extends), obj);
+};
+
+/**
+ * Étendre un objet récursivement.
+ *
+ * @param {any} obj L'objet qui sera étendu.
+ * @returns {Promise<any>} Une promesse contenant l'objet étendu.
+ */
+export const transform = function (obj) {
+    return walkAsync(obj, inherit);
+};
+
+/**
+ * Charge un objet JSON depuis une URL.
+ *
+ * @param {string} url L'URL du fichier JSON.
+ * @returns {Promise<any>} Une promesse contenant l'objet.
+ */
+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, ".")));
+};
+
+/**
+ * Parse une chaine de caractères.
+ *
+ * @param {string} text La chaine de caractères qui sera parsée.
+ * @returns {any} L'objet.
+ */
+export const parse = function (text) {
+    return transform(JSON.parse(text));
+};

package/types/index.d.ts

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

package/types/jfather.d.ts

@@ -0,0 +1,9 @@
+export function walk(obj: any, fn: Function): any;
+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 transform(obj: any): Promise<any>;
+export function load(url: string): Promise<any>;
+export function parse(text: string): any;