hinted-tree-merger 6.0.2 → 6.1.1

package/README.md

@@ -1,5 +1,6 @@
 [![npm](https://img.shields.io/npm/v/hinted-tree-merger.svg)](https://www.npmjs.com/package/hinted-tree-merger)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Typed with TypeScript](https://flat.badgen.net/badge/icon/Typed?icon=typescript\&label\&labelColor=blue\&color=555555)](https://typescriptlang.org)
 [![bundlejs](https://deno.bundlejs.com/?q=hinted-tree-merger\&badge=detailed)](https://bundlejs.com/?q=hinted-tree-merger)
 [![downloads](http://img.shields.io/npm/dm/hinted-tree-merger.svg?style=flat-square)](https://npmjs.org/package/hinted-tree-merger)
 [![GitHub Issues](https://img.shields.io/github/issues/arlac77/hinted-tree-merger.svg?style=flat-square)](https://github.com/arlac77/hinted-tree-merger/issues)
@@ -50,38 +51,46 @@ const r = merge( undefined, [ { k:1, e:2}, { k:3 }]);
 
 *   [hintFor](#hintfor)
     *   [Parameters](#parameters)
-*   [mergeSkip](#mergeskip)
+*   [Actions](#actions)
     *   [Parameters](#parameters-1)
-*   [mergeArrays](#mergearrays)
+*   [mergeSkip](#mergeskip)
     *   [Parameters](#parameters-2)
-*   [merge](#merge)
+*   [mergeArrays](#mergearrays)
     *   [Parameters](#parameters-3)
-*   [hasDeleteHint](#hasdeletehint)
+*   [merge](#merge)
     *   [Parameters](#parameters-4)
-*   [isToBeRemoved](#istoberemoved)
+*   [hasDeleteHint](#hasdeletehint)
     *   [Parameters](#parameters-5)
-*   [hintFreeValue](#hintfreevalue)
+*   [isToBeRemoved](#istoberemoved)
     *   [Parameters](#parameters-6)
-*   [indexFor](#indexfor)
+*   [hintFreeValue](#hintfreevalue)
     *   [Parameters](#parameters-7)
-*   [keyFor](#keyfor)
+*   [indexFor](#indexfor)
     *   [Parameters](#parameters-8)
-*   [sortObjectsByKeys](#sortobjectsbykeys)
+*   [keyFor](#keyfor)
     *   [Parameters](#parameters-9)
+*   [sortObjectsByKeys](#sortobjectsbykeys)
+    *   [Parameters](#parameters-10)
+*   [compareWithDefinedOrder](#comparewithdefinedorder)
+    *   [Parameters](#parameters-11)
+*   [matchingIndex](#matchingindex)
+    *   [Parameters](#parameters-12)
 *   [match](#match)
+*   [cmp](#cmp)
+    *   [Parameters](#parameters-13)
 *   [compareVersion](#compareversion)
-    *   [Parameters](#parameters-10)
+    *   [Parameters](#parameters-14)
 *   [unionVersion](#unionversion)
-    *   [Parameters](#parameters-11)
+    *   [Parameters](#parameters-15)
 *   [VersionMapper](#versionmapper)
 *   [mergeVersionsWithFilter](#mergeversionswithfilter)
-    *   [Parameters](#parameters-12)
+    *   [Parameters](#parameters-16)
 *   [mergeVersions](#mergeversions)
-    *   [Parameters](#parameters-13)
+    *   [Parameters](#parameters-17)
 *   [mergeVersionsPreferNumeric](#mergeversionsprefernumeric)
-    *   [Parameters](#parameters-14)
+    *   [Parameters](#parameters-18)
 *   [walk](#walk)
-    *   [Parameters](#parameters-15)
+    *   [Parameters](#parameters-19)
 
 ## hintFor
 
@@ -92,6 +101,15 @@ Construct hint for a given path.
 *   `hints` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
 *   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
 
+## Actions
+
+Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
+
+### Parameters
+
+*   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+*   `hints` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+
 ## mergeSkip
 
 Skip merging use left side always.
@@ -111,7 +129,7 @@ Skip merging use left side always.
 *   `a` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** 
 *   `b` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** 
 *   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-*   `actions` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)**  (optional, default `nullAction`)
+*   `actions` **[Actions](#actions)**  (optional, default `nullAction`)
 *   `hints` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
 
 ## merge
@@ -123,7 +141,7 @@ Merge to values.
 *   `a` **any** 
 *   `b` **any** 
 *   `path`  
-*   `actions` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>**  (optional, default `nullAction`)
+*   `actions` **[Actions](#actions)**  (optional, default `nullAction`)
 *   `hints` **any**&#x20;
 
 Returns **any** merged value
@@ -146,7 +164,7 @@ Should value be removed.
 *   `value` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
 *   `fromTemplate` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
 
-Returns **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** true if fromTemplate tells is to delete value
+Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** true if fromTemplate tells is to delete value
 
 ## hintFreeValue
 
@@ -177,7 +195,7 @@ Deliver key value to identify object.
 *   `object` **any**&#x20;
 *   `hint` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**&#x20;
 
-Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
+Returns **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))**&#x20;
 
 ## sortObjectsByKeys
 
@@ -190,10 +208,35 @@ Sort keys in source.
 
 Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** source with keys orderd by compare function
 
+## compareWithDefinedOrder
+
+### Parameters
+
+*   `a` **any**&#x20;
+*   `b` **any**&#x20;
+*   `definedOrder` &#x20;
+
+## matchingIndex
+
+### Parameters
+
+*   `value` **any**&#x20;
+
+Returns **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**&#x20;
+
 ## match
 
 url means highest version
 
+## cmp
+
+### Parameters
+
+*   `a` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>**&#x20;
+*   `b` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>**&#x20;
+
+Returns **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**&#x20;
+
 ## compareVersion
 
 Compare two versions.

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "hinted-tree-merger",
-  "version": "6.0.2",
+  "version": "6.1.1",
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
+  "types": "./types/index.d.mts",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "default": "./src/index.mjs",
+      "types": "./types/index.d.mts"
+    }
   },
   "description": "merges two trees guided with hints",
   "keywords": [
@@ -24,24 +28,26 @@
   ],
   "license": "BSD-2-Clause",
   "scripts": {
-    "prepare": "npx playwright install",
+    "prepare": "tsc --allowJs --declaration --emitDeclarationOnly --declarationDir types -t esnext -m esnext --module nodenext --moduleResolution nodenext ./src**/*.mjs",
     "test": "npm run test:browser-ava && npm run test:ava",
     "test:ava": "ava --timeout 4m tests/*-ava.mjs tests/*-ava-node.mjs",
     "test:browser-ava": "browser-ava --headless --no-keep-open tests/*-ava.mjs tests/*-ava-browser.mjs",
     "cover": "c8 -x 'tests/**/*' --temp-directory build/tmp ava --timeout 4m tests/*-ava.mjs tests/*-ava-node.mjs && c8 report -r lcov -o build/coverage --temp-directory build/tmp",
     "docs": "documentation readme --section=API ./src/**/*.mjs",
-    "lint": "npm run lint:docs",
-    "lint:docs": "documentation lint ./src/**/*.mjs"
+    "lint": "npm run lint:docs && npm run lint:tsc",
+    "lint:docs": "documentation lint ./src/**/*.mjs",
+    "lint:tsc": "tsc --allowJs --checkJs --noEmit -t esnext -m esnext --module nodenext --moduleResolution nodenext ./src**/*.mjs"
   },
   "devDependencies": {
     "ava": "^6.1.1",
     "browser-ava": "^2.2.0",
     "c8": "^9.1.0",
     "documentation": "^14.0.3",
-    "semantic-release": "^23.0.2"
+    "semantic-release": "^23.0.2",
+    "typescript": "^5.3.3"
   },
   "engines": {
-    "node": ">=20.11.0"
+    "node": ">=20.11.1"
   },
   "repository": {
     "type": "git",
@@ -56,7 +62,8 @@
       "arlac77/template-arlac77-github",
       "arlac77/template-browser-ava",
       "arlac77/template-javascript-component",
-      "arlac77/template-node-component"
+      "arlac77/template-node-component",
+      "arlac77/template-typescript"
     ]
   }
 }

package/src/merger.mjs

@@ -12,9 +12,15 @@ import {
   compareWithDefinedOrder,
   sortObjectsByKeys
 } from "./util.mjs";
-
 import { hintFor } from "./hint.mjs";
 
+/**
+ * @callback Actions
+ * @param {Object} options
+ * @param {Object} hints
+ */
+
+
 function appendPath(path, suffix, separator = "") {
   return path === undefined || path.length === 0
     ? suffix
@@ -33,7 +39,7 @@ export function mergeSkip(a, b, path, actions, hints) {
  * @param {Array} a
  * @param {Array} b
  * @param {string} path
- * @param {Function} actions
+ * @param {Actions} actions
  * @param {Object} hints
  */
 export function mergeArrays(a, b, path, actions = nullAction, hints) {
@@ -116,7 +122,7 @@ export function mergeArrays(a, b, path, actions = nullAction, hints) {
  * Merge to values.
  * @param {any} a
  * @param {any} b
- * @param {Object[]} actions
+ * @param {Actions} actions
  * @param {any} hints
  * @return {any} merged value
  */

package/src/string-expressions.mjs

@@ -1,5 +1,10 @@
 import { nullAction } from "./util.mjs";
-import { hintFor, DELETE_HINT_REGEX, OVERWRITE_HINT_REGEX, LIKE_HINT_REGEX } from "./hint.mjs";
+import {
+  hintFor,
+  DELETE_HINT_REGEX,
+  OVERWRITE_HINT_REGEX,
+  LIKE_HINT_REGEX
+} from "./hint.mjs";
 
 export function mergeExpressions(a, b, path, actions = nullAction, hints) {
   if (a === undefined && b === undefined) {
@@ -63,7 +68,7 @@ export function decodeExpressions(script, hint) {
       like,
       overwrite,
       op: "&&",
-      args: script.split(/\s*&&\s*/).map(v=>v.trim())
+      args: script.split(/\s*&&\s*/).map(v => v.trim())
     };
   }
   return { op: "", args: [script.trim()], overwrite, like };
@@ -84,11 +89,12 @@ function mergeLIKE(a, b) {
   const args = x => (x === undefined ? [] : x.args);
 
   //const t = args(a).concat(args(b));
-  const t="";
-  console.log(args(b))
+  const t = "";
+  console.log(args(b));
 
   return {
     op: "&&",
+    // @ts-ignore
     args: t.filter((item, pos) => t.indexOf(item) === pos)
   };
 }

package/src/util.mjs

@@ -4,7 +4,7 @@ import {
   OVERWRITE_HINT_REGEX
 } from "./hint.mjs";
 
-export function nullAction() {}
+export function nullAction(options,hint) {}
 
 export function asArray(a) {
   return Array.isArray(a) ? a : a === undefined ? [] : [a];
@@ -42,6 +42,7 @@ export function hasDeleteHint(value, expected) {
     }
 
     if (value === `-${expected}`) {
+      // @ts-ignore
       return expected;
     }
   }
@@ -53,7 +54,7 @@ export function hasDeleteHint(value, expected) {
  * Should value be removed.
  * @param {string} value
  * @param {string} fromTemplate
- * @return {number} true if fromTemplate tells is to delete value
+ * @return {Object} true if fromTemplate tells is to delete value
  */
 export function isToBeRemoved(value, fromTemplate) {
   if (fromTemplate === undefined) {
@@ -301,7 +302,7 @@ function normalizeValue(value, hint) {
  * Deliver key value to identify object.
  * @param {any} object
  * @param {Object} hint
- * @return {string}
+ * @return {string|undefined}
  */
 export function keyFor(object, hint) {
   if (hint?.key) {
@@ -319,8 +320,6 @@ export function keyFor(object, hint) {
       .map(k => normalizeValue(object[k], hint))
       .find(v => v !== undefined);
   }
-
-  return undefined;
 }
 
 /**
@@ -339,11 +338,22 @@ export function sortObjectsByKeys(source, compare) {
   return sorted;
 }
 
+  /**
+   * 
+   * @param {any} a 
+   * @param {any} b
+   */
 export function compareWithDefinedOrder(a, b, definedOrder) {
+  /**
+   * 
+   * @param {any} value 
+   * @returns {number}
+   */
   function matchingIndex(value) {
     for (const i in definedOrder) {
       const o = definedOrder[i];
       if ((o instanceof RegExp && value.match(o)) || o === value) {
+        // @ts-ignore
         return i;
       }
     }

package/src/versions.mjs

@@ -112,8 +112,15 @@ export function composeVersion(decomposed) {
   return joinSlots(decomposed.lower);
 }
 
+/**
+ * 
+ * @param {number[]} a 
+ * @param {number[]} b 
+ * @returns {number}
+ */
 function cmp(a, b) {
   for (const i in a) {
+    // @ts-ignore
     if (i >= a.length) {
       break;
     }
@@ -140,9 +147,6 @@ export function compareVersion(a, b) {
   const da = decomposeVersion(a);
   const db = decomposeVersion(b);
 
-  //console.log(a, da);
-  //console.log(b, db);
-
   const r = cmp(da.lower, db.lower);
   return r === 0 ? cmp(da.upper, db.upper) : r;
 }

package/types/hint.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Construct hint for a given path.
+ * @param {Object} hints
+ * @param {string} path
+ */
+export function hintFor(hints: any, path: string): any;
+export const SHORT_DELETE_HINT_REGEX: RegExp;
+export const DELETE_HINT_REGEX: RegExp;
+export const OVERWRITE_HINT_REGEX: RegExp;
+export const LIKE_HINT_REGEX: RegExp;

package/types/index.d.mts

@@ -0,0 +1,6 @@
+export * from "./versions.mjs";
+export * from "./walker.mjs";
+export * from "./string-expressions.mjs";
+export * from "./util.mjs";
+export * from "./merger.mjs";
+export * from "./reanimate-hints.mjs";

package/types/merger.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Skip merging use left side always.
+ */
+export function mergeSkip(a: any, b: any, path: any, actions: any, hints: any): any;
+/**
+ *
+ * @param {Array} a
+ * @param {Array} b
+ * @param {string} path
+ * @param {Actions} actions
+ * @param {Object} hints
+ */
+export function mergeArrays(a: any[], b: any[], path: string, actions: Actions, hints: any): any[];
+/**
+ * Merge to values.
+ * @param {any} a
+ * @param {any} b
+ * @param {Actions} actions
+ * @param {any} hints
+ * @return {any} merged value
+ */
+export function merge(a: any, b: any, path: any, actions: Actions, hints: any): any;
+export type Actions = (options: any, hints: any) => any;

package/types/reanimate-hints.d.mts

@@ -0,0 +1 @@
+export function reanimateHints(hints: any): any;

package/types/string-expressions.d.mts

@@ -0,0 +1,15 @@
+export function mergeExpressions(a: any, b: any, path: any, actions: typeof nullAction, hints: any): any;
+export function decodeExpressions(script: any, hint: any): {
+    op: string;
+    args: any;
+    like?: undefined;
+    overwrite?: undefined;
+} | {
+    like: boolean;
+    overwrite: boolean;
+    op: string;
+    args: any;
+};
+export function mergeDecodedExpressions(dest: any, source: any): any;
+export function encodeExpressions(encoded: any): any;
+import { nullAction } from "./util.mjs";

package/types/util.d.mts

@@ -0,0 +1,54 @@
+export function nullAction(options: any, hint: any): void;
+export function asArray(a: any): any[];
+export function compare(a: any, b: any): 0 | 1 | -1;
+/**
+ * @param {any} value
+ * @param {string|Function} expected
+ * @return {string|boolean}
+ */
+export function hasDeleteHint(value: any, expected: string | Function): string | boolean;
+/**
+ * Should value be removed.
+ * @param {string} value
+ * @param {string} fromTemplate
+ * @return {Object} true if fromTemplate tells is to delete value
+ */
+export function isToBeRemoved(value: string, fromTemplate: string): any;
+/**
+ * Remove hint(s) form a value.
+ * @param {string|any} value
+ * @returns {any} value without hint
+ */
+export function hintFreeValue(value: string | any): any;
+export function removeHintedValues(object: any, removeEmpty?: boolean): any;
+export function deepCopy(object: any): any;
+export function isEmpty(a: any): boolean;
+export function isEqual(a: any, b: any, hints: any): boolean;
+export function isScalar(a: any): boolean;
+/**
+ * Find best insertion point for b[i] in a.
+ * @param {any[]} b
+ * @param {number} i
+ * @param {any[]} a
+ */
+export function indexFor(b: any[], i: number, a: any[]): number;
+/**
+ * Deliver key value to identify object.
+ * @param {any} object
+ * @param {Object} hint
+ * @return {string|undefined}
+ */
+export function keyFor(object: any, hint: any): string | undefined;
+/**
+ * Sort keys in source.
+ * @param {Object} source
+ * @param compare
+ * @return {Object} source with keys orderd by compare function
+ */
+export function sortObjectsByKeys(source: any, compare: any): any;
+/**
+ *
+ * @param {any} a
+ * @param {any} b
+ */
+export function compareWithDefinedOrder(a: any, b: any, definedOrder: any): number;

package/types/versions.d.mts

@@ -0,0 +1,63 @@
+export function decomposeVersion(value: any): {
+    lower: any;
+    upper: any;
+};
+export function composeVersion(decomposed: any): any;
+/**
+ * Compare two versions.
+ *
+ * @param {string|number} a
+ * @param {string|number} b
+ * @return {number} -1 if a < b, 0 if a == b and 1 if a > b
+ */
+export function compareVersion(a: string | number, b: string | number): number;
+/**
+ * Forms union of two versions.
+ * @param {string|number} a
+ * @param {string|number} b
+ * @return {string|number}
+ */
+export function unionVersion(a: string | number, b: string | number): string | number;
+export function toBeRemoved(value: any): boolean;
+/**
+ * maps version values (to number)
+ * @typedef {Function} VersionMapper
+ */
+/**
+ * Merge and filter two sets of version (expressions).
+ * @param {string|string[]|number|number[]} a
+ * @param {string|string[]|number|number[]} b
+ * @param {string} path location in the tree
+ * @param {Function} actions cb to notify about the actual selection
+ * @param {Object} hints
+ * @param {VersionMapper} filter
+ * @return {string|string[]|number|number[]} merged set of version expressions
+ */
+export function mergeVersionsWithFilter(a: string | string[] | number | number[], b: string | string[] | number | number[], path: string, actions: Function, hints: any, filter: VersionMapper): string | string[] | number | number[];
+/**
+ * merge two sets of version (expressions)
+ * @param {string|string[]|number|number[]} a
+ * @param {string|string[]|number|number[]} b
+ * @param {string} path location in the tree
+ * @param {Function} actions cb to notify about the actual selection
+ * @param {Object} hints
+ * @return {string|string[]|number|number[]} merged set of version expressions
+ */
+export function mergeVersions(a: string | string[] | number | number[], b: string | string[] | number | number[], path: string, actions: Function, hints: any): string | string[] | number | number[];
+export function mergeVersionsLargest(a: any, b: any, path: any, actions: any, hints: any): string | number | string[] | number[];
+export function mergeVersionsSmallest(a: any, b: any, path: any, actions: any, hints: any): string | number | string[] | number[];
+/**
+ * Same as mergeVersions but merge result are converted into
+ * numbers if possible
+ * @param {string|string[]|number|number[]} a
+ * @param {string|string[]|number|number[]} b
+ * @param {string} path location in the tree
+ * @param {Function} actions cb to notify about the actual selection
+ * @param {Object} hints
+ * @return {string|string[]|number|number[]} merged set of version expressions
+ */
+export function mergeVersionsPreferNumeric(a: string | string[] | number | number[], b: string | string[] | number | number[], path: string, actions: Function, hints: any): string | string[] | number | number[];
+/**
+ * maps version values (to number)
+ */
+export type VersionMapper = Function;

package/types/walker.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Iterates over all members.
+ * @param {any} value
+ * @param {any[]} path
+ */
+export function walk(value: any, path?: any[], parents?: any[]): any;