@equinor/cpl-utils 0.0.5 → 0.1.0

package/dist/index.d.mts

@@ -1,3 +1,98 @@
+type TreeNode<T> = T & {
+    children?: TreeNode<T>[];
+};
+interface BuildTreeFromArrayOptions {
+    /**
+     * Whether to throw Error if parent node of an element is not found.
+     * @default false
+     */
+    throwOnInvalidTree?: boolean;
+}
+/**
+ * Builds a tree structure from a flat array of items.
+ *
+ * @template T - The type of each item in the array.
+ * @param items - The flat array of items.
+ * @param idKey - The key representing the value of the id of each item, e.g. "id"
+ * @param parentIdKey - The key representing the value of the parent id of each item, e.g. "parentId"
+ * @param options - Options for strict mode.
+ * @returns Array of TreeNodes.
+ *
+ * @example
+ * // Basic usage with id/parentId keys
+ * const items = [
+ *   { id: 1, parentId: null, name: 'Root' },
+ *   { id: 2, parentId: 1, name: 'Child 1' },
+ *   { id: 3, parentId: 1, name: 'Child 2' },
+ *   { id: 4, parentId: 2, name: 'Grandchild' }
+ * ];
+ * const tree = buildTreeNodes(items, 'id', 'parentId');
+ * // tree = [{ id: 1, ...children: [...] }]
+ *
+ * @example
+ * // Custom keys
+ * const items = [
+ *   { key: 'a', parent: null },
+ *   { key: 'b', parent: 'a' },
+ *   { key: 'c', parent: 'b' }
+ * ];
+ * const tree = buildTreeNodes(items, 'key', 'parent');
+ *
+ * @example
+ * // Strict mode (throws on missing parent)
+ * buildTreeNodes(items, 'id', 'parentId', { throwOnInvalidTree: true });
+ *
+ * @example
+ * // TypeScript usage
+ * interface Node { id: number; parentId: number | null; name: string }
+ * const tree = buildTreeNodes<Node>(items, 'id', 'parentId');
+ */
+declare function buildTreeNodes<T extends object>(items: T[], idKey: keyof T, parentIdKey: keyof T, options?: BuildTreeFromArrayOptions): TreeNode<T>[];
+
+/**
+ * Efficiently checks for circular dependencies in a flat array of objects with id and parentId.
+ * Returns true if a cycle is found, false otherwise.
+ *
+ * @template T - The type of each item in the array.
+ * @param items - The flat array of items.
+ * @param idKey - The key representing the value of the id of each item, e.g. "id"
+ * @param parentIdKey - The key representing the value of the parent id of each item, e.g. "parentId"
+ * @returns {boolean} True if a circular dependency is found, false otherwise.
+ *
+ * @example
+ * // No circular dependency
+ * const items = [
+ *   { id: 1, parentId: null },
+ *   { id: 2, parentId: 1 },
+ *   { id: 3, parentId: 2 }
+ * ];
+ * hasCircularDependency(items, 'id', 'parentId'); // false
+ *
+ * @example
+ * // Circular dependency (3 -> 1 -> 2 -> 3)
+ * const items = [
+ *   { id: 1, parentId: 2 },
+ *   { id: 2, parentId: 3 },
+ *   { id: 3, parentId: 1 }
+ * ];
+ * hasCircularDependency(items, 'id', 'parentId'); // true
+ *
+ * @example
+ * // Custom keys
+ * const items = [
+ *   { key: 'a', parent: null },
+ *   { key: 'b', parent: 'a' },
+ *   { key: 'c', parent: 'b' }
+ * ];
+ * hasCircularDependency(items, 'key', 'parent'); // false
+ *
+ * @example
+ * // TypeScript usage
+ * interface Node { id: number; parentId: number | null }
+ * hasCircularDependency<Node>(items, 'id', 'parentId');
+ */
+declare function hasCircularDependency<T extends object>(items: T[], idKey: keyof T, parentIdKey: keyof T): boolean;
+
 /**
  * A function ensuring returning whether an item is undefined or not. If not undefined, it will exclude undefined from the type.
  *
@@ -49,4 +144,4 @@ declare function itemIsDefined<T>(item: T): item is Exclude<typeof item, undefin
  */
 declare function objectHasOwnProperty<Key extends PropertyKey>(object: object, key: Key): object is Record<Key, unknown>;
 
-export { itemIsDefined, objectHasOwnProperty };
+export { type TreeNode, buildTreeNodes, hasCircularDependency, itemIsDefined, objectHasOwnProperty };

package/dist/index.d.ts

@@ -1,3 +1,98 @@
+type TreeNode<T> = T & {
+    children?: TreeNode<T>[];
+};
+interface BuildTreeFromArrayOptions {
+    /**
+     * Whether to throw Error if parent node of an element is not found.
+     * @default false
+     */
+    throwOnInvalidTree?: boolean;
+}
+/**
+ * Builds a tree structure from a flat array of items.
+ *
+ * @template T - The type of each item in the array.
+ * @param items - The flat array of items.
+ * @param idKey - The key representing the value of the id of each item, e.g. "id"
+ * @param parentIdKey - The key representing the value of the parent id of each item, e.g. "parentId"
+ * @param options - Options for strict mode.
+ * @returns Array of TreeNodes.
+ *
+ * @example
+ * // Basic usage with id/parentId keys
+ * const items = [
+ *   { id: 1, parentId: null, name: 'Root' },
+ *   { id: 2, parentId: 1, name: 'Child 1' },
+ *   { id: 3, parentId: 1, name: 'Child 2' },
+ *   { id: 4, parentId: 2, name: 'Grandchild' }
+ * ];
+ * const tree = buildTreeNodes(items, 'id', 'parentId');
+ * // tree = [{ id: 1, ...children: [...] }]
+ *
+ * @example
+ * // Custom keys
+ * const items = [
+ *   { key: 'a', parent: null },
+ *   { key: 'b', parent: 'a' },
+ *   { key: 'c', parent: 'b' }
+ * ];
+ * const tree = buildTreeNodes(items, 'key', 'parent');
+ *
+ * @example
+ * // Strict mode (throws on missing parent)
+ * buildTreeNodes(items, 'id', 'parentId', { throwOnInvalidTree: true });
+ *
+ * @example
+ * // TypeScript usage
+ * interface Node { id: number; parentId: number | null; name: string }
+ * const tree = buildTreeNodes<Node>(items, 'id', 'parentId');
+ */
+declare function buildTreeNodes<T extends object>(items: T[], idKey: keyof T, parentIdKey: keyof T, options?: BuildTreeFromArrayOptions): TreeNode<T>[];
+
+/**
+ * Efficiently checks for circular dependencies in a flat array of objects with id and parentId.
+ * Returns true if a cycle is found, false otherwise.
+ *
+ * @template T - The type of each item in the array.
+ * @param items - The flat array of items.
+ * @param idKey - The key representing the value of the id of each item, e.g. "id"
+ * @param parentIdKey - The key representing the value of the parent id of each item, e.g. "parentId"
+ * @returns {boolean} True if a circular dependency is found, false otherwise.
+ *
+ * @example
+ * // No circular dependency
+ * const items = [
+ *   { id: 1, parentId: null },
+ *   { id: 2, parentId: 1 },
+ *   { id: 3, parentId: 2 }
+ * ];
+ * hasCircularDependency(items, 'id', 'parentId'); // false
+ *
+ * @example
+ * // Circular dependency (3 -> 1 -> 2 -> 3)
+ * const items = [
+ *   { id: 1, parentId: 2 },
+ *   { id: 2, parentId: 3 },
+ *   { id: 3, parentId: 1 }
+ * ];
+ * hasCircularDependency(items, 'id', 'parentId'); // true
+ *
+ * @example
+ * // Custom keys
+ * const items = [
+ *   { key: 'a', parent: null },
+ *   { key: 'b', parent: 'a' },
+ *   { key: 'c', parent: 'b' }
+ * ];
+ * hasCircularDependency(items, 'key', 'parent'); // false
+ *
+ * @example
+ * // TypeScript usage
+ * interface Node { id: number; parentId: number | null }
+ * hasCircularDependency<Node>(items, 'id', 'parentId');
+ */
+declare function hasCircularDependency<T extends object>(items: T[], idKey: keyof T, parentIdKey: keyof T): boolean;
+
 /**
  * A function ensuring returning whether an item is undefined or not. If not undefined, it will exclude undefined from the type.
  *
@@ -49,4 +144,4 @@ declare function itemIsDefined<T>(item: T): item is Exclude<typeof item, undefin
  */
 declare function objectHasOwnProperty<Key extends PropertyKey>(object: object, key: Key): object is Record<Key, unknown>;
 
-export { itemIsDefined, objectHasOwnProperty };
+export { type TreeNode, buildTreeNodes, hasCircularDependency, itemIsDefined, objectHasOwnProperty };

package/dist/index.js

@@ -20,22 +20,97 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  buildTreeNodes: () => buildTreeNodes,
+  hasCircularDependency: () => hasCircularDependency,
   itemIsDefined: () => itemIsDefined,
   objectHasOwnProperty: () => objectHasOwnProperty
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/itemIsDefined.ts
-function itemIsDefined(item) {
-  return item !== void 0;
+// src/has-circular-dependency.ts
+function hasCircularDependency(items, idKey, parentIdKey) {
+  const parentMap = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    parentMap.set(item[idKey], item[parentIdKey]);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function visit(id) {
+    if (stack.has(id)) return true;
+    if (visited.has(id)) return false;
+    stack.add(id);
+    const parentId = parentMap.get(id);
+    if (parentId !== void 0 && parentId !== null && parentMap.has(parentId)) {
+      if (visit(parentId)) return true;
+    }
+    stack.delete(id);
+    visited.add(id);
+    return false;
+  }
+  for (const id of parentMap.keys()) {
+    if (visit(id)) return true;
+  }
+  return false;
 }
 
 // src/objectHasOwnProperty.ts
 function objectHasOwnProperty(object, key) {
   return Object.prototype.hasOwnProperty.call(object, key);
 }
+
+// src/build-tree-nodes.ts
+function buildTreeNodes(items, idKey, parentIdKey, options = {}) {
+  const { throwOnInvalidTree = false } = options;
+  if (!items.length) {
+    return [];
+  }
+  if (throwOnInvalidTree && hasCircularDependency(items, idKey, parentIdKey)) {
+    throw new Error("Circular dependency detected");
+  }
+  const lookupTable = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (!objectHasOwnProperty(item, idKey)) {
+      throw new Error(`Item is missing idKey named '${String(idKey)}'`);
+    }
+    lookupTable.set(item[idKey], item);
+  }
+  const rootNodes = [];
+  for (const item of lookupTable.values()) {
+    const id = item[idKey];
+    const parentId = item[parentIdKey];
+    const node = lookupTable.get(id);
+    if (!node) {
+      throw new Error(`Node with id '${id}' not found in lookup table.`);
+    }
+    if (parentId === void 0 || parentId === null) {
+      rootNodes.push(node);
+      continue;
+    }
+    const parentNode = lookupTable.get(parentId);
+    if (!parentNode) {
+      const message = `Parent node with id '${parentId}' not found for node with id '${id}'.`;
+      if (throwOnInvalidTree) {
+        throw new Error(message);
+      }
+      rootNodes.push(node);
+      continue;
+    }
+    if (!parentNode.children) {
+      parentNode.children = [];
+    }
+    parentNode.children.push(node);
+  }
+  return rootNodes;
+}
+
+// src/itemIsDefined.ts
+function itemIsDefined(item) {
+  return item !== void 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  buildTreeNodes,
+  hasCircularDependency,
   itemIsDefined,
   objectHasOwnProperty
 });

package/dist/index.mjs

@@ -1,13 +1,86 @@
-// src/itemIsDefined.ts
-function itemIsDefined(item) {
-  return item !== void 0;
+// src/has-circular-dependency.ts
+function hasCircularDependency(items, idKey, parentIdKey) {
+  const parentMap = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    parentMap.set(item[idKey], item[parentIdKey]);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function visit(id) {
+    if (stack.has(id)) return true;
+    if (visited.has(id)) return false;
+    stack.add(id);
+    const parentId = parentMap.get(id);
+    if (parentId !== void 0 && parentId !== null && parentMap.has(parentId)) {
+      if (visit(parentId)) return true;
+    }
+    stack.delete(id);
+    visited.add(id);
+    return false;
+  }
+  for (const id of parentMap.keys()) {
+    if (visit(id)) return true;
+  }
+  return false;
 }
 
 // src/objectHasOwnProperty.ts
 function objectHasOwnProperty(object, key) {
   return Object.prototype.hasOwnProperty.call(object, key);
 }
+
+// src/build-tree-nodes.ts
+function buildTreeNodes(items, idKey, parentIdKey, options = {}) {
+  const { throwOnInvalidTree = false } = options;
+  if (!items.length) {
+    return [];
+  }
+  if (throwOnInvalidTree && hasCircularDependency(items, idKey, parentIdKey)) {
+    throw new Error("Circular dependency detected");
+  }
+  const lookupTable = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (!objectHasOwnProperty(item, idKey)) {
+      throw new Error(`Item is missing idKey named '${String(idKey)}'`);
+    }
+    lookupTable.set(item[idKey], item);
+  }
+  const rootNodes = [];
+  for (const item of lookupTable.values()) {
+    const id = item[idKey];
+    const parentId = item[parentIdKey];
+    const node = lookupTable.get(id);
+    if (!node) {
+      throw new Error(`Node with id '${id}' not found in lookup table.`);
+    }
+    if (parentId === void 0 || parentId === null) {
+      rootNodes.push(node);
+      continue;
+    }
+    const parentNode = lookupTable.get(parentId);
+    if (!parentNode) {
+      const message = `Parent node with id '${parentId}' not found for node with id '${id}'.`;
+      if (throwOnInvalidTree) {
+        throw new Error(message);
+      }
+      rootNodes.push(node);
+      continue;
+    }
+    if (!parentNode.children) {
+      parentNode.children = [];
+    }
+    parentNode.children.push(node);
+  }
+  return rootNodes;
+}
+
+// src/itemIsDefined.ts
+function itemIsDefined(item) {
+  return item !== void 0;
+}
 export {
+  buildTreeNodes,
+  hasCircularDependency,
   itemIsDefined,
   objectHasOwnProperty
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/cpl-utils",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "license": "MIT",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -13,7 +13,8 @@
     "tsup": "^8.3.6",
     "typedoc": "^0.27.6",
     "typedoc-plugin-markdown": "^4.4.1",
-    "@equinor/cpl-eslint-config": "0.0.8",
+    "vitest": "^3.2.4",
+    "@equinor/cpl-eslint-config": "0.0.9",
     "@equinor/cpl-typescript-config": "0.0.2"
   },
   "publishConfig": {
@@ -23,6 +24,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --external react",
     "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
     "dev": "tsup src/index.ts --format esm,cjs --watch --dts --external react",
+    "test": "vitest --run",
     "typedoc": "typedoc && rm ./typedoc/README.mdx",
     "typedoc:watch": "typedoc --watch --preserveWatchOutput",
     "lint": "TIMING=1 eslint . --fix",