@likec4/core 1.17.1 → 1.18.0

package/src/utils/fqn.ts

@@ -1,11 +1,23 @@
-import type { LiteralUnion } from 'type-fest'
 import type { Element, Fqn } from '../types'
 import { compareNatural } from './compare-natural'
 import { isString } from './guards'
 
 type Predicate<T> = (x: T) => boolean
 
-export function nameFromFqn(fqn: LiteralUnion<Fqn, string>) {
+export function parentFqn<E extends string>(fqn: E): E | null {
+  const lastDot = fqn.lastIndexOf('.')
+  if (lastDot > 0) {
+    return fqn.slice(0, lastDot) as E
+  }
+  return null
+}
+
+export function parentFqnPredicate<T extends { parent: Fqn | null }>(parent: Fqn): Predicate<T> {
+  const prefix = parent + '.'
+  return (e: T) => !!e.parent && (e.parent === parent || e.parent.startsWith(prefix))
+}
+
+export function nameFromFqn<E extends string>(fqn: E) {
   const lastDot = fqn.lastIndexOf('.')
   if (lastDot > 0) {
     return fqn.slice(lastDot + 1)
@@ -14,7 +26,7 @@ export function nameFromFqn(fqn: LiteralUnion<Fqn, string>) {
   }
 }
 
-export function isAncestor<E extends { id: Fqn }>(
+export function isAncestor<E extends { id: string }>(
   ...args: [ancestor: string, another: string] | [ancestor: E, another: E]
 ) {
   const ancestor = isString(args[0]) ? args[0] : args[0].id
@@ -22,7 +34,7 @@ export function isAncestor<E extends { id: Fqn }>(
   return another.startsWith(ancestor + '.')
 }
 
-export function isSameHierarchy<E extends { id: Fqn }>(one: E | Fqn, another: E | Fqn) {
+export function isSameHierarchy<E extends string | { id: Fqn }>(one: E, another: E) {
   const first = isString(one) ? one : one.id
   const second = isString(another) ? another : another.id
   return first === second || second.startsWith(first + '.') || first.startsWith(second + '.')
@@ -38,7 +50,44 @@ export function notDescendantOf(ancestors: Element[]): (e: Element) => boolean {
   return (e: Element) => !isDescendant(e)
 }
 
-export function commonAncestor<IDs extends string>(first: Fqn<IDs>, second: Fqn<IDs>) {
+/**
+ * How deep in the hierarchy the element is.
+ * Root element has depth 1
+ */
+export function hierarchyDepth<E extends string | { id: Fqn }>(elementOfFqn: E): number {
+  const first = isString(elementOfFqn) ? elementOfFqn : elementOfFqn.id
+  return first.split('.').length
+}
+
+/**
+ * Calculate the distance as number of steps from one element to another, i.e.
+ * going up to the common ancestor, then going down to the other element.
+ * Sibling distance is always 1
+ *
+ * Can be used for hierarchical clustering
+ */
+export function hierarchyDistance<E extends string | { id: Fqn }>(one: E, another: E) {
+  const first = isString(one) ? one as Fqn : one.id
+  const second = isString(another) ? another as Fqn : another.id
+
+  if (first === second) {
+    return 0
+  }
+
+  const firstDepth = hierarchyDepth(first)
+  const secondDepth = hierarchyDepth(second)
+
+  if (isSameHierarchy(first, second)) {
+    return Math.abs(firstDepth - secondDepth)
+  }
+
+  const ancestor = commonAncestor(first as Fqn, second as Fqn)
+  const ancestorDepth = ancestor ? hierarchyDepth(ancestor) : 0
+
+  return firstDepth + secondDepth - (2 * ancestorDepth + 1)
+}
+
+export function commonAncestor<E extends string>(first: E, second: E) {
   const parentA = parentFqn(first)
   const parentB = parentFqn(second)
   if (parentA === parentB) {
@@ -50,35 +99,22 @@ export function commonAncestor<IDs extends string>(first: Fqn<IDs>, second: Fqn<
 
   const a = first.split('.')
   const b = second.split('.')
-  let ancestor: Fqn<IDs> | null = null
+  let ancestor: E | null = null
 
   while (a.length > 1 && b.length > 1 && !!a[0] && a[0] === b[0]) {
-    ancestor = (ancestor ? `${ancestor}.${a[0]}` : a[0]) as Fqn<IDs>
+    ancestor = (ancestor ? `${ancestor}.${a[0]}` : a[0]) as E
     a.shift()
     b.shift()
   }
   return ancestor
 }
 
-export function parentFqn<IDs extends string>(fqn: Fqn<IDs>): Fqn<IDs> | null {
-  const lastDot = fqn.lastIndexOf('.')
-  if (lastDot > 0) {
-    return fqn.slice(0, lastDot) as Fqn<IDs>
-  }
-  return null
-}
-
-export function parentFqnPredicate<T extends { parent: Fqn | null }>(parent: Fqn): Predicate<T> {
-  const prefix = parent + '.'
-  return (e: T) => !!e.parent && (e.parent === parent || e.parent.startsWith(prefix))
-}
-
 /**
  * Get all ancestor elements (i.e. parent, parent’s parent, etc.)
- * (from closest to root)
+ * going up from parent to the root
  */
-export function ancestorsFqn<IDs extends string>(fqn: Fqn<IDs>): Fqn<IDs>[] {
-  const path = fqn.split('.') as Fqn<IDs>[]
+export function ancestorsFqn<Id extends string>(fqn: Id): Id[] {
+  const path = fqn.split('.') as Id[]
   path.pop()
   if (path.length === 0) {
     return []
@@ -88,9 +124,9 @@ export function ancestorsFqn<IDs extends string>(fqn: Fqn<IDs>): Fqn<IDs>[] {
       acc.push(part)
       return acc
     }
-    acc.unshift(`${acc[0]}.${part}` as Fqn<IDs>)
+    acc.unshift(`${acc[0]}.${part}` as Id)
     return acc
-  }, [] as Fqn<IDs>[])
+  }, [] as Id[])
 }
 
 /**
@@ -123,8 +159,8 @@ export function compareByFqnHierarchically<T extends { id: string }>(a: T, b: T)
   return compareFqnHierarchically(a.id, b.id)
 }
 
-type IterableContainer<T = unknown> = ReadonlyArray<T> | readonly []
-type ReorderedArray<T extends IterableContainer> = {
+export type IterableContainer<T = unknown> = ReadonlyArray<T> | readonly []
+export type ReorderedArray<T extends IterableContainer> = {
   -readonly [P in keyof T]: T[number]
 }
 
@@ -139,6 +175,26 @@ export function sortByFqnHierarchically<T extends { id: string }, A extends Iter
     .map(({ item }) => item) as ReorderedArray<A>
 }
 
+/**
+ * Keeps initial order of the elements, but ensures that parents are before children
+ */
+export function sortParentsFirst<T extends { id: string }, A extends IterableContainer<T>>(
+  array: A
+): ReorderedArray<A> {
+  const result = [] as T[]
+  const items = [...array]
+  let item
+  while ((item = items.shift())) {
+    const itemId = item.id
+    let parentIndx
+    while ((parentIndx = items.findIndex(parent => isAncestor(parent.id, itemId))) !== -1) {
+      result.push(...items.splice(parentIndx, 1))
+    }
+    result.push(item)
+  }
+  return result as ReorderedArray<A>
+}
+
 export function sortNaturalByFqn<T extends { id: string }, A extends IterableContainer<T>>(
   array: A
 ): ReorderedArray<A> {

package/src/utils/getOrCreate.ts

@@ -0,0 +1,42 @@
+// export function getOrCreate<K, V>(map: Map<K, V>): Map<K, V> & {
+//   get(key: K, create: (key: K) => V): V
+//   get(key: K): V | undefined
+// }
+// export function getOrCreate<K, V>(map: Map<K, V>, key: K, create: (key: K) => V): V
+// export function getOrCreate<K, V>(map: Map<K, V>, key?: K, create?: (key: K) => V) {
+export function getOrCreate<K, V>(map: Map<K, V>, key: K, create: (key: K) => V) {
+  let entry = map.get(key)
+  if (!entry) {
+    entry = create(key)
+    map.set(key, entry)
+  }
+  return entry
+}
+
+// export class BetterMap<K, V> extends Map<K, V> {
+//   constructor(iterable?: Iterable<readonly [K, V]> | null) {
+//     super(iterable)
+//   }
+
+//   /**
+//    * Returns the element associated with the specified key.
+//    * If no element is associated with the specified key, and a create function is provided, a new element will be created and stored.
+//    * @example
+//    * ```ts
+//    * const map = new BetterMap<Fqn, Element>()
+//    *
+//    * map.get(fqn, () => factory.createElement(fqn))
+//    *
+//    */
+//   override get(key: K, create: (key: K) => V): V
+//   override get(key: K): V | undefined
+//   override get(key: K, create?: (key: K) => V) {
+//     const entry = super.get(key)
+//     if (!entry && create) {
+//       const newEntry = create(key)
+//       this.set(key, newEntry)
+//       return newEntry
+//     }
+//     return entry
+//   }
+// }

package/src/utils/graphlib.ts

@@ -0,0 +1,10 @@
+import dagre from '@dagrejs/dagre'
+
+const Graph = dagre.graphlib.Graph
+
+export { Graph }
+
+export const postorder = dagre.graphlib.alg.postorder
+export const preorder = dagre.graphlib.alg.preorder
+export const findCycles = dagre.graphlib.alg.findCycles
+export const isAcyclic = dagre.graphlib.alg.isAcyclic

package/src/utils/index.ts

@@ -1,6 +1,9 @@
-export * from './commonHead'
+export * from './common-head'
 export * from './compare-natural'
 export * from './fqn'
+export * from './getOrCreate'
 export * from './guards'
 export * from './promises'
 export * from './relations'
+export * from './set'
+export * from './string-hash'

package/src/utils/object-hash.ts

@@ -0,0 +1,3 @@
+import objectHash from 'object-hash'
+
+export { objectHash }

package/src/utils/set.ts

@@ -0,0 +1,76 @@
+import {
+  intersection as _intersection,
+  symmetricDifference as _symmetricDifference,
+  union as _union
+} from 'mnemonist/set'
+import type { NonEmptyArray } from '../types/_common'
+
+/**
+ * Returns new set as a union of given sets
+ * Keeps order of elements
+ */
+export function union<T>(...sets: NonEmptyArray<ReadonlySet<T>>): Set<T> {
+  return _union(...sets as any)
+}
+
+/**
+ * Returns new set as an intersection of all sets
+ * Keeps order from the first set
+ */
+export function intersection<T>(first: ReadonlySet<T>, ...sets: NonEmptyArray<ReadonlySet<T>>): Set<T> {
+  let result = new Set<T>()
+  // If first set is empty, return empty set
+  if (first.size === 0) {
+    return result
+  }
+  let other = sets.length > 1 ? _intersection(...sets as any) : sets[0]
+  if (other.size === 0) {
+    return result
+  }
+  for (const value of first) {
+    if (other.has(value)) {
+      result.add(value)
+    }
+  }
+  return result
+}
+
+export function difference<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): Set<T> {
+  if (a.size === 0) {
+    return new Set<T>()
+  }
+  if (b.size === 0) {
+    return new Set(a)
+  }
+  let result = new Set<T>()
+  for (const value of a) {
+    if (!b.has(value)) {
+      result.add(value)
+    }
+  }
+  return result
+}
+
+export function equals<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): boolean {
+  return a.size === b.size && [...a].every(value => b.has(value))
+}
+
+export function symmetricDifference<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): Set<T> {
+  return _symmetricDifference(a as Set<T>, b as Set<T>)
+}
+
+export function hasIntersection<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): boolean {
+  if (a.size === 0 || b.size === 0) {
+    return false
+  }
+  // Swap sets to iterate over smaller set
+  if (b.size < a.size) {
+    ;[a, b] = [b, a]
+  }
+  for (const value of a) {
+    if (b.has(value)) {
+      return true
+    }
+  }
+  return false
+}

package/src/utils/string-hash.ts

@@ -0,0 +1,16 @@
+import { invariant } from '../errors'
+
+/**
+ * @see https://gist.github.com/victor-homyakov/bcb7d7911e4a388b1c810f8c3ce17bcf
+ */
+export function stringHash(str: string) {
+  let hash = 5381
+  const len = str.length
+  invariant(len > 0, 'stringHash: empty string')
+
+  for (let i = 0; i < len; i++) {
+    hash = (hash * 33) ^ str.charCodeAt(i)
+  }
+
+  return (hash >>> 0).toString(36)
+}