@likec4/core 1.18.0 → 1.19.1

package/src/utils/fqn.ts

@@ -1,8 +1,8 @@
-import type { Element, Fqn } from '../types'
+import type { Fqn } from '../types'
 import { compareNatural } from './compare-natural'
 import { isString } from './guards'
 
-type Predicate<T> = (x: T) => boolean
+export type Predicate<T> = (x: T) => boolean
 
 export function parentFqn<E extends string>(fqn: E): E | null {
   const lastDot = fqn.lastIndexOf('.')
@@ -17,7 +17,7 @@ export function parentFqnPredicate<T extends { parent: Fqn | null }>(parent: Fqn
   return (e: T) => !!e.parent && (e.parent === parent || e.parent.startsWith(prefix))
 }
 
-export function nameFromFqn<E extends string>(fqn: E) {
+export function nameFromFqn<E extends string>(fqn: E): string {
   const lastDot = fqn.lastIndexOf('.')
   if (lastDot > 0) {
     return fqn.slice(lastDot + 1)
@@ -26,35 +26,66 @@ export function nameFromFqn<E extends string>(fqn: E) {
   }
 }
 
-export function isAncestor<E extends { id: string }>(
-  ...args: [ancestor: string, another: string] | [ancestor: E, another: E]
+const asString: <E extends string | { id: string }>(e: E) => string = e => (isString(e) ? e : e.id)
+
+/**
+ * Check if one element is an ancestor of another
+ * Composable version
+ * @signature
+ *  isAncestor(another)(ancestor)
+ */
+export function isAncestor<A extends string | { id: string }>(another: NoInfer<A>): (ancestor: A) => boolean
+/**
+ * Check if one element is an ancestor of another
+ * @signature
+ *   isAncestor(ancestor, another)
+ */
+export function isAncestor<A extends string | { id: string }>(ancestor: A, another: A): boolean
+
+export function isAncestor<T extends string>(
+  arg1: T | WithId<T>,
+  arg2?: NoInfer<T> | WithId<NoInfer<T>>,
 ) {
-  const ancestor = isString(args[0]) ? args[0] : args[0].id
-  const another = isString(args[1]) ? args[1] : args[1].id
-  return another.startsWith(ancestor + '.')
+  const arg1Id = asString(arg1)
+  if (arg2) {
+    const arg2Id = asString(arg2)
+    return arg2Id.startsWith(arg1Id + '.')
+  }
+  return (ancestor: T | WithId<T>) => {
+    const ancestorId = asString(ancestor)
+    return arg1Id.startsWith(ancestorId + '.')
+  }
 }
 
-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
+export function isSameHierarchy<T extends string>(
+  one: NoInfer<T> | WithId<NoInfer<T>>,
+): (another: T | WithId<T>) => boolean
+export function isSameHierarchy<T extends string>(one: T | WithId<T>, another: T | WithId<T>): boolean
+export function isSameHierarchy<T extends string>(one: T | WithId<T>, another?: T | WithId<T>) {
+  if (!another) {
+    return (b: T | WithId<T>) => isSameHierarchy(one, b)
+  }
+  const first = asString(one)
+  const second = asString(another)
   return first === second || second.startsWith(first + '.') || first.startsWith(second + '.')
 }
 
-export function isDescendantOf<E extends { id: Fqn }>(ancestors: E[]): (e: E) => boolean {
-  const predicates = ancestors.flatMap(a => [(e: E) => e.id === a.id, (e: E) => isAncestor(a, e)])
-  return (e: E) => predicates.some(p => p(e))
-}
+type WithId<T> = { id: T }
 
-export function notDescendantOf(ancestors: Element[]): (e: Element) => boolean {
-  const isDescendant = isDescendantOf(ancestors)
-  return (e: Element) => !isDescendant(e)
+export function isDescendantOf<T extends string>(ancestor: WithId<T>): (descedant: WithId<T>) => boolean
+export function isDescendantOf<T extends string>(descedant: WithId<T>, ancestor: WithId<T>): boolean
+export function isDescendantOf<T extends string>(descedant: WithId<T>, ancestor?: WithId<T>) {
+  if (!ancestor) {
+    return (d: WithId<T>) => isAncestor(descedant, d)
+  }
+  return isAncestor(ancestor, descedant)
 }
 
 /**
  * How deep in the hierarchy the element is.
  * Root element has depth 1
  */
-export function hierarchyDepth<E extends string | { id: Fqn }>(elementOfFqn: E): number {
+export function hierarchyLevel<E extends string | { id: Fqn }>(elementOfFqn: E): number {
   const first = isString(elementOfFqn) ? elementOfFqn : elementOfFqn.id
   return first.split('.').length
 }
@@ -66,7 +97,7 @@ export function hierarchyDepth<E extends string | { id: Fqn }>(elementOfFqn: E):
  *
  * Can be used for hierarchical clustering
  */
-export function hierarchyDistance<E extends string | { id: Fqn }>(one: E, another: E) {
+export function hierarchyDistance<E extends string | { id: Fqn }>(one: E, another: E): number {
   const first = isString(one) ? one as Fqn : one.id
   const second = isString(another) ? another as Fqn : another.id
 
@@ -74,39 +105,36 @@ export function hierarchyDistance<E extends string | { id: Fqn }>(one: E, anothe
     return 0
   }
 
-  const firstDepth = hierarchyDepth(first)
-  const secondDepth = hierarchyDepth(second)
+  const firstDepth = hierarchyLevel(first)
+  const secondDepth = hierarchyLevel(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
+  const ancestorDepth = ancestor ? hierarchyLevel(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) {
-    return parentA
-  }
-  if (!parentA || !parentB) {
+export function commonAncestor<E extends string>(first: E, second: E): E | null {
+  const a = first.split('.')
+  if (a.length < 2) {
     return null
   }
-
-  const a = first.split('.')
   const b = second.split('.')
-  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 E
-    a.shift()
-    b.shift()
+  if (b.length < 2) {
+    return null
+  }
+  let ancestor = [] as string[]
+  for (let i = 0; i < Math.min(a.length, b.length) - 1 && a[i] === b[i]; i++) {
+    ancestor.push(a[i]!)
+  }
+  if (ancestor.length === 0) {
+    return null
   }
-  return ancestor
+  return ancestor.join('.') as E
 }
 
 /**
@@ -155,7 +183,7 @@ export function compareFqnHierarchically<T extends string = string>(a: T, b: T):
   }
 }
 
-export function compareByFqnHierarchically<T extends { id: string }>(a: T, b: T) {
+export function compareByFqnHierarchically<T extends { id: string }>(a: T, b: T): -1 | 0 | 1 {
   return compareFqnHierarchically(a.id, b.id)
 }
 
@@ -164,8 +192,33 @@ export type ReorderedArray<T extends IterableContainer> = {
   -readonly [P in keyof T]: T[number]
 }
 
+/**
+ * Sorts an array of objects hierarchically based on their fully qualified names (FQN).
+ * Objects are sorted by the number of segments in their FQN (defined by dot-separated ID).
+ *
+ * @typeParam T - Object type that contains an 'id' string property
+ * @typeParam A - Type extending IterableContainer of T
+ *
+ * @param array - Array of objects to be sorted
+ * @returns A new array with items sorted by their FQN hierarchy depth (number of segments)
+ *
+ * @example
+ * ```ts
+ * const items = [
+ *   { id: "a.b.c" },
+ *   { id: "a" },
+ *   { id: "a.b" }
+ * ];
+ * sortByFqnHierarchically(items);
+ * // Result: [
+ * //   { id: "a" },
+ * //   { id: "a.b" },
+ * //   { id: "a.b.c" }
+ * // ]
+ * ```
+ */
 export function sortByFqnHierarchically<T extends { id: string }, A extends IterableContainer<T>>(
-  array: A
+  array: A,
 ): ReorderedArray<A> {
   return array
     .map(item => ({ item, fqn: item.id.split('.') }))
@@ -175,34 +228,72 @@ export function sortByFqnHierarchically<T extends { id: string }, A extends Iter
     .map(({ item }) => item) as ReorderedArray<A>
 }
 
+function findTopAncestor<T extends { id: string }>(items: T[], item: T): T | null {
+  let parent = item
+  for (const e of items) {
+    if (isAncestor(e, parent)) {
+      parent = e
+    }
+  }
+  return parent !== item ? parent : null
+}
+
 /**
  * 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
+  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))
+    let parent
+    while ((parent = findTopAncestor(items, item))) {
+      result.push(items.splice(items.indexOf(parent), 1)[0]!)
     }
     result.push(item)
   }
   return result as ReorderedArray<A>
 }
 
+/**
+ * Sorts an array of objects naturally by their fully qualified name (FQN) identifier.
+ *
+ * @template T - Type of objects containing an 'id' string property
+ * @template A - Type extending IterableContainer of T
+ *
+ * @param first - Optional. Either the array to sort or the sort direction ('asc'|'desc')
+ * @param sort - Optional. The sort direction ('asc'|'desc'). Defaults to 'asc' if not specified
+ *
+ * @example
+ * // As a function that returns a sorting function
+ * const sorted = sortNaturalByFqn('desc')(myArray);
+ *
+ * // Direct array sorting
+ * const sorted = sortNaturalByFqn(myArray, 'desc');
+ */
+export function sortNaturalByFqn(
+  sort?: 'asc' | 'desc',
+): <T extends { id: string }, A extends IterableContainer<T>>(array: A) => ReorderedArray<A>
 export function sortNaturalByFqn<T extends { id: string }, A extends IterableContainer<T>>(
-  array: A
-): ReorderedArray<A> {
+  array: A,
+  sort?: 'asc' | 'desc',
+): ReorderedArray<A>
+export function sortNaturalByFqn<T extends { id: string }, A extends IterableContainer<T>>(
+  array?: A | 'asc' | 'desc',
+  sort?: 'asc' | 'desc',
+) {
+  if (!array || isString(array)) {
+    const dir = array ?? 'asc'
+    return (arr: A) => sortNaturalByFqn(arr, dir)
+  }
+  const dir = sort === 'desc' ? -1 : 1
   return array
     .map(item => ({ item, fqn: item.id.split('.') }))
     .sort((a, b) => {
       if (a.fqn.length !== b.fqn.length) {
-        return a.fqn.length - b.fqn.length
+        return (a.fqn.length - b.fqn.length) * dir
       }
       for (let i = 0; i < a.fqn.length; i++) {
         const compare = compareNatural(a.fqn[i], b.fqn[i])

package/src/utils/getOrCreate.ts

@@ -4,7 +4,7 @@
 // }
 // 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) {
+export function getOrCreate<K, V>(map: Map<K, V>, key: K, create: (key: K) => V): V {
   let entry = map.get(key)
   if (!entry) {
     entry = create(key)

package/src/utils/index.ts

@@ -1,9 +1,75 @@
-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'
+import DefaultMap from 'mnemonist/default-map'
+import LinkedList from 'mnemonist/linked-list'
+
+export { DefaultMap, LinkedList }
+
+export {
+  commonHead,
+} from './common-head'
+
+export {
+  compareNatural,
+} from './compare-natural'
+export {
+  ancestorsFqn,
+  commonAncestor,
+  compareByFqnHierarchically,
+  compareFqnHierarchically,
+  hierarchyDistance,
+  hierarchyLevel,
+  isAncestor,
+  isDescendantOf,
+  isSameHierarchy,
+  type IterableContainer,
+  nameFromFqn,
+  parentFqn,
+  type ReorderedArray,
+  sortByFqnHierarchically,
+  sortNaturalByFqn,
+  sortParentsFirst,
+} from './fqn'
+
+export {
+  getOrCreate,
+} from './getOrCreate'
+
+export {
+  hasAtLeast,
+  isNonEmptyArray,
+  isString,
+} from './guards'
+export {
+  ifilter,
+  ifind,
+  iflat,
+  imap,
+  ireduce,
+  isIterable,
+  isome,
+  iunique,
+  toArray,
+  toSet,
+} from './iterable'
+export {
+  delay,
+} from './promises'
+
+export {
+  compareRelations,
+} from './relations'
+
+export {
+  difference,
+  equals as equalsSet,
+  intersection,
+  symmetricDifference,
+  union,
+} from './set'
+
+export {
+  stringHash,
+} from './string-hash'
+
+export {
+  objectHash,
+} from './object-hash'

package/src/utils/iterable/_types.ts

@@ -0,0 +1,5 @@
+import { isNonNullish } from 'remeda'
+
+export function isIterable<T, I extends Iterable<T>>(something: I | unknown): something is Iterable<T> {
+  return isNonNullish(something) && typeof something === 'object' && Symbol.iterator in something
+}

package/src/utils/iterable/filter.ts

@@ -0,0 +1,55 @@
+import { isFunction } from 'remeda'
+import { invariant } from '../../errors'
+import type { IteratorLike } from '../../types'
+
+/**
+ * Filters an iterable based on a predicate.
+ * Composabel first version of `ifilter`.
+ * @signature
+ *    ifilter(predicate)(data)
+ */
+export function ifilter<T, S extends T>(
+  predicate: (v: T) => v is S,
+): (iterable: Iterable<T>) => IteratorLike<S>
+export function ifilter<T>(
+  predicate: (v: T) => boolean,
+): (iterable: Iterable<T>) => IteratorLike<T>
+
+/**
+ * Filters an iterable based on a predicate.
+ * Data first version of `ifilter`.
+ * @signature
+ *    ifilter(data, predicate)
+ * @example
+ *    ifilter(new Set([1, 2, 3]), x => x % 2 === 1) // => Iterable<[1, 3]>
+ */
+export function ifilter<T, S extends T>(
+  iterable: Iterable<T>,
+  predicate: (v: T) => v is S,
+): IteratorLike<S>
+export function ifilter<T>(
+  iterable: Iterable<T>,
+  predicate: (v: T) => boolean,
+): IteratorLike<T>
+
+export function ifilter(
+  arg1: unknown,
+  arg2?: unknown,
+): IteratorLike<unknown> | ((it: Iterable<unknown>) => IteratorLike<unknown>) {
+  const pred = (arg2 ?? arg1) as (v: any) => boolean
+  invariant(isFunction(pred))
+
+  function* _filter(iter: Iterable<unknown>): IteratorLike<unknown> {
+    for (const value of iter) {
+      if (pred(value)) {
+        yield value
+      }
+    }
+    return
+  }
+
+  if (!arg2) {
+    return _filter
+  }
+  return _filter(arg1 as Iterable<unknown>)
+}

package/src/utils/iterable/find.ts

@@ -0,0 +1,36 @@
+import { isFunction } from 'remeda'
+import { invariant } from '../../errors'
+
+/**
+ * Finds the first element in the iterable that satisfies the predicate.
+ * Composable first version of `find`.
+ * @signature
+ *   ifind(predicate)(data)
+ */
+export function ifind<T>(predicate: (item: T) => boolean): (iterable: Iterable<T>) => T | undefined
+/**
+ * Finds the first element in the iterable that satisfies the predicate.
+ * Data first version of `find`.
+ * @signature
+ *  ifind(data, predicate)
+ */
+export function ifind<T>(iterable: Iterable<T>, predicate: (item: T) => boolean): T | undefined
+
+export function ifind(arg1: unknown, arg2?: unknown) {
+  const pred = (arg2 ?? arg1) as (v: any) => boolean
+  invariant(isFunction(pred))
+
+  function _find(iter: Iterable<unknown>) {
+    for (const value of iter) {
+      if (pred(value)) {
+        return value
+      }
+    }
+    return
+  }
+
+  if (!arg2) {
+    return _find
+  }
+  return _find(arg1 as Iterable<unknown>)
+}

package/src/utils/iterable/flat.ts

@@ -0,0 +1,17 @@
+import type { IteratorLike } from '../../types'
+
+export function iflat(): <T>(iterable: Iterable<IteratorLike<T>>) => IteratorLike<T>
+export function iflat<T>(iterable: Iterable<IteratorLike<T>>): IteratorLike<T>
+
+export function iflat<T>(
+  iterable?: Iterable<IteratorLike<T>>,
+): IteratorLike<T> | ((iterable: Iterable<IteratorLike<T>>) => IteratorLike<T>) {
+  return iterable ? _iflat(iterable) : _iflat
+}
+
+function* _iflat<T>(iterable: Iterable<IteratorLike<T>>): IteratorLike<T> {
+  for (const inner of iterable) {
+    yield* inner
+  }
+  return
+}

package/src/utils/iterable/index.ts

@@ -0,0 +1,13 @@
+export { isIterable } from './_types'
+
+/**
+ * operators
+ */
+export { ifilter } from './filter'
+export { ifind } from './find'
+export { iflat } from './flat'
+export { imap } from './map'
+export { ireduce } from './reduce'
+export { isome } from './some'
+export { toArray, toSet } from './to'
+export { iunique } from './unique'

package/src/utils/iterable/map.ts

@@ -0,0 +1,40 @@
+import { isFunction } from 'remeda'
+import { invariant } from '../../errors'
+import type { IteratorLike } from '../../types'
+
+type MapFunction<T, S> = (item: T) => S
+
+/**
+ * Maps an iterable using a mapper function.
+ * Composable first version of `imap`.
+ * @signature
+ *   imap(mapper)(data)
+ */
+export function imap<T, S>(mapper: MapFunction<T, S>): (iterable: Iterable<T>) => IteratorLike<S>
+/**
+ * Maps an iterable using a mapper function.
+ * Data first version of `imap`.
+ * @signature
+ *   imap(data, mapper)
+ */
+export function imap<T, S>(iterable: Iterable<T>, mapper: MapFunction<T, S>): IteratorLike<S>
+
+export function imap(
+  arg1: unknown,
+  arg2?: unknown,
+): IteratorLike<unknown> | ((it: Iterable<unknown>) => IteratorLike<unknown>) {
+  const mapper = (arg2 ?? arg1) as MapFunction<any, any>
+  invariant(isFunction(mapper))
+
+  function* _map(iter: Iterable<unknown>): IteratorLike<unknown> {
+    for (const value of iter) {
+      yield mapper(value)
+    }
+    return
+  }
+
+  if (!arg2) {
+    return _map
+  }
+  return _map(arg1 as Iterable<unknown>)
+}

package/src/utils/iterable/reduce.ts

@@ -0,0 +1,24 @@
+import { isDefined, isFunction } from 'remeda'
+import { invariant } from '../../errors'
+
+export function ireduce<T, R>(reducer: (acc: R, item: T) => R, initialValue: R): (iterable: Iterable<T>) => R
+export function ireduce<T, R>(iterable: Iterable<T>, reducer: (acc: R, item: T) => R, initialValue: R): R
+export function ireduce<T, R>(
+  arg1: unknown,
+  arg2: unknown,
+  arg3?: unknown,
+): R | ((iterable: Iterable<T>) => R) {
+  const reducer = (isDefined(arg3) ? arg2 : arg1) as (acc: R, item: T) => R
+  const initialValue = arg3 ?? arg2
+  invariant(isFunction(reducer))
+
+  function _reduce(iter: Iterable<T>): R {
+    let acc = initialValue as R
+    for (const value of iter) {
+      acc = reducer(acc, value)
+    }
+    return acc
+  }
+
+  return isDefined(arg3) ? _reduce(arg1 as Iterable<T>) : _reduce
+}

package/src/utils/iterable/some.ts

@@ -0,0 +1,36 @@
+import { isFunction } from 'remeda'
+import { invariant } from '../../errors'
+
+/**
+ * Checks if at least one element in the iterable satisfies the predicate.
+ * Composable first version of `some`.
+ * @signature
+ *   isome(predicate)(data)
+ */
+export function isome<T>(predicate: (item: T) => boolean): (iterable: Iterable<T>) => boolean
+/**
+ * Checks if at least one element in the iterable satisfies the predicate.
+ * Data first version of `some`.
+ * @signature
+ *  isome(data, predicate)
+ */
+export function isome<T>(iterable: Iterable<T>, predicate: (item: T) => boolean): boolean
+
+export function isome<T>(arg1: unknown, arg2?: unknown): boolean | ((iterable: Iterable<T>) => boolean) {
+  const pred = (arg2 ?? arg1) as (v: any) => boolean
+  invariant(isFunction(pred))
+
+  function _some(iter: Iterable<unknown>): boolean {
+    for (const value of iter) {
+      if (pred(value)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  if (!arg2) {
+    return _some
+  }
+  return _some(arg1 as Iterable<unknown>)
+}

package/src/utils/iterable/to.ts

@@ -0,0 +1,19 @@
+export function toArray(): <T>(iterable: Iterable<T> | ArrayLike<T>) => T[]
+export function toArray<T>(iterable: Iterable<T> | ArrayLike<T>): T[]
+export function toArray<T>(
+  iterable?: Iterable<T> | ArrayLike<T>
+): T[] | (<T>(iterable: Iterable<T> | ArrayLike<T>) => T[]) {
+  if (iterable) {
+    return Array.from(iterable)
+  }
+  return (it) => Array.from(it)
+}
+
+export function toSet(): <T>(iterable: Iterable<T>) => Set<T>
+export function toSet<T>(iterable: Iterable<T>): Set<T>
+export function toSet<T>(iterable?: Iterable<T>): Set<T> | ((iterable: Iterable<T>) => Set<T>) {
+  if (iterable) {
+    return new Set(iterable)
+  }
+  return (it) => new Set(it)
+}

package/src/utils/iterable/unique.ts

@@ -0,0 +1,29 @@
+import type { IteratorLike } from '../../types'
+
+/**
+ * Returns an iterable that yields only unique values.
+ * It uses a Set to keep track of the values.
+ */
+export function iunique(): <T>(iterable: Iterable<T>) => IteratorLike<T>
+export function iunique<T>(iterable: Iterable<T>): IteratorLike<T>
+
+export function iunique<T>(iterable?: Iterable<T>): IteratorLike<T> | ((iterable: Iterable<T>) => IteratorLike<T>) {
+  if (iterable) {
+    return (function*(): IteratorLike<T> {
+      yield* _iunique(iterable)
+      return
+    })()
+  }
+  return _iunique
+}
+
+function* _iunique<T>(iterable: Iterable<T>): IteratorLike<T> {
+  const seen = new Set<T>()
+  for (const item of iterable) {
+    if (!seen.has(item)) {
+      seen.add(item)
+      yield item
+    }
+  }
+  return
+}