hinted-tree-merger 6.0.1 → 6.1.0

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)

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "hinted-tree-merger",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
+  "types": "./types/index.d.mts",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "types": "./types/index.d.mts",
+      "default": "./src/index.mjs"
+    }
   },
   "description": "merges two trees guided with hints",
   "keywords": [
@@ -24,21 +28,23 @@
   ],
   "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"
@@ -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,16 @@ 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 +40,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,13 +123,13 @@ 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
  */
 export function merge(a, b, path, actions = nullAction, hints) {
   if (isScalar(a)) {
-    if (b !== undefined && !isEqual(a, b)) {
+    if (b !== undefined && b !== null && !isEqual(a, b)) {
       const hint = hintFor(hints, path);
       b = hint.keepHints ? deepCopy(b) : removeHintedValues(b);
       actions({ add: b, path }, hint);

package/src/util.mjs

@@ -53,7 +53,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 +301,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 +319,6 @@ export function keyFor(object, hint) {
       .map(k => normalizeValue(object[k], hint))
       .find(v => v !== undefined);
   }
-
-  return undefined;
 }
 
 /**
@@ -339,6 +337,11 @@ export function sortObjectsByKeys(source, compare) {
   return sorted;
 }
 
+  /**
+   * 
+   * @param {any} a 
+   * @param {any} b
+   */
 export function compareWithDefinedOrder(a, b, definedOrder) {
   function matchingIndex(value) {
     for (const i in definedOrder) {

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