@likec4/core 1.17.1 → 1.19.0

package/src/model/connection/deployment/DeploymentConnectionModel.ts

@@ -0,0 +1,178 @@
+import { invariant } from '../../../errors'
+import type { IteratorLike } from '../../../types'
+import { stringHash } from '../../../utils'
+import { customInspectSymbol } from '../../../utils/const'
+import { equals } from '../../../utils/set'
+import {
+  type DeployedInstanceModel,
+  type DeploymentElementModel,
+  type DeploymentRelationModel,
+  DeploymentNodeModel,
+  RelationshipsAccum,
+} from '../../DeploymentElementModel'
+import type { RelationshipModel } from '../../RelationModel'
+import type { AnyAux } from '../../types'
+import type { Connection } from '../Connection'
+
+/**
+ * Connection is ephemeral entity, result of a resolving relationships between source and target.
+ * Includes direct relationships and/or between their nested elements.
+ */
+export class DeploymentConnectionModel<M extends AnyAux = AnyAux>
+  implements Connection<DeploymentElementModel<M>, M['EdgeId']>
+{
+  constructor(
+    public readonly source: DeploymentNodeModel<M> | DeployedInstanceModel<M>,
+    public readonly target: DeploymentNodeModel<M> | DeployedInstanceModel<M>,
+    public readonly relations: RelationshipsAccum<M>,
+  ) {
+    this.id = stringHash(`deployment:${source.id}:${target.id}`) as M['EdgeId']
+  }
+
+  readonly id: M['EdgeId']
+
+  /**
+   * Human readable expression of the connection
+   * Mostly used for testing and debugging
+   */
+  get expression(): string {
+    return `${this.source.id} -> ${this.target.id}`
+  }
+
+  private _boundary: DeploymentNodeModel<M> | null | undefined
+  /**
+   * Common ancestor of the source and target elements.
+   * Represents the boundary of the connection.
+   */
+  get boundary(): DeploymentNodeModel<M> | null {
+    this._boundary ??= this.source.commonAncestor(this.target)
+    return this._boundary
+  }
+
+  nonEmpty(): boolean {
+    return this.relations.nonEmpty
+  }
+
+  [customInspectSymbol](
+    // @ts-ignore
+    depth,
+    // @ts-ignore
+    inspectOptions,
+    // @ts-ignore
+    inspect,
+  ) {
+    const asString = this.toString()
+
+    // Trick so that node displays the name of the constructor
+    Object.defineProperty(asString, 'constructor', {
+      value: DeploymentConnectionModel,
+      enumerable: false,
+    })
+
+    return asString
+  }
+
+  toString() {
+    const model = [...this.relations.model].map(c => '    ' + c.expression)
+    if (model.length) {
+      model.unshift('  model:')
+    } else {
+      model.unshift('  model: []')
+    }
+    const deployment = [...this.relations.deployment].map(c => '    ' + c.expression)
+    if (deployment.length) {
+      deployment.unshift('  deployment:')
+    } else {
+      deployment.unshift('  deployment: []')
+    }
+    return [
+      this.expression,
+      ...model,
+      ...deployment,
+    ].join('\n')
+  }
+
+  /**
+   * Check if connection contains deployment relation,
+   * that is directly connected to source or target.
+   */
+  public hasDirectDeploymentRelation(): boolean {
+    for (const relation of this.relations.deployment) {
+      if (relation.source.id === this.source.id || relation.target.id === this.target.id) {
+        return true
+      }
+    }
+    return false
+  }
+
+  public *values(): IteratorLike<RelationshipModel<M> | DeploymentRelationModel<M>> {
+    yield* this.relations.model
+    yield* this.relations.deployment
+  }
+
+  /**
+   * Merge with another connection, if it has the same source and target.
+   * Returns new connection with union of relationships.
+   */
+  public mergeWith(other: DeploymentConnectionModel<M>) {
+    invariant(this.source.id === other.source.id, 'Cannot merge connections with different sources')
+    invariant(this.target.id === other.target.id, 'Cannot merge connections with different targets')
+    return new DeploymentConnectionModel(
+      this.source,
+      this.target,
+      this.relations.union(other.relations),
+    )
+  }
+
+  public difference(other: DeploymentConnectionModel<M>) {
+    return new DeploymentConnectionModel(
+      this.source,
+      this.target,
+      this.relations.difference(other.relations),
+    )
+  }
+
+  public intersect(other: DeploymentConnectionModel<M>) {
+    return new DeploymentConnectionModel(
+      this.source,
+      this.target,
+      this.relations.intersect(other.relations),
+    )
+  }
+
+  public equals(other: Connection): boolean {
+    invariant(other instanceof DeploymentConnectionModel, 'Other should ne DeploymentConnectionModel')
+    return this.id === other.id
+      && this.source.id === other.source.id
+      && this.target.id === other.target.id
+      && equals(this.relations.model, other.relations.model)
+      && equals(this.relations.deployment, other.relations.deployment)
+  }
+
+  /**
+   * Creates a clone of the current `DeploymentConnectionModel` instance with optional overrides.
+   * if `null` is provided in overrides, the corresponding relation set will be empty.
+   */
+  public update(overrides?: {
+    model?: ReadonlySet<RelationshipModel<M>> | null
+    deployment?: ReadonlySet<DeploymentRelationModel<M>> | null
+  }): DeploymentConnectionModel<M> {
+    if (overrides) {
+      overrides = {
+        model: this.relations.model,
+        deployment: this.relations.deployment,
+        ...overrides,
+      }
+    }
+    return new DeploymentConnectionModel(
+      this.source,
+      this.target,
+      overrides
+        ? new RelationshipsAccum(
+          overrides.model ?? new Set(),
+          overrides.deployment ?? new Set(),
+        )
+        : this.relations,
+    )
+  }
+}

package/src/model/connection/deployment/find.ts

@@ -0,0 +1,120 @@
+import { isSameHierarchy } from '../../../utils'
+import type { DeploymentElementModel } from '../../DeploymentElementModel'
+import type { AnyAux } from '../../types'
+import { DeploymentConnectionModel } from './DeploymentConnectionModel'
+
+/**
+ * Resolve connection from source to target
+ * If direction is `both`, also look for reverse connection
+ *
+ * @default direction directed
+ */
+export function findConnection<M extends AnyAux>(
+  source: DeploymentElementModel<M>,
+  target: DeploymentElementModel<NoInfer<M>>,
+  direction: 'directed',
+):
+  | readonly [DeploymentConnectionModel<M>]
+  | readonly []
+export function findConnection<M extends AnyAux>(
+  source: DeploymentElementModel<M>,
+  target: DeploymentElementModel<NoInfer<M>>,
+  direction: 'both',
+):
+  | readonly [DeploymentConnectionModel<M>, DeploymentConnectionModel<M>]
+  | readonly [DeploymentConnectionModel<M>]
+  | readonly []
+export function findConnection<M extends AnyAux>(
+  source: DeploymentElementModel<M>,
+  target: DeploymentElementModel<NoInfer<M>>,
+  direction?: 'directed' | 'both',
+):
+  | readonly [DeploymentConnectionModel<M>, DeploymentConnectionModel<M>]
+  | readonly [DeploymentConnectionModel<M>]
+  | readonly []
+export function findConnection<M extends AnyAux>(
+  source: DeploymentElementModel<M>,
+  target: DeploymentElementModel<NoInfer<M>>,
+  direction: 'directed' | 'both' = 'directed',
+) {
+  if (source === target) {
+    return []
+  }
+  if (isSameHierarchy(source, target)) {
+    return []
+  }
+  const directedIntersection = source.allOutgoing.intersect(target.allIncoming)
+
+  const directed = directedIntersection.nonEmpty
+    ? [
+      new DeploymentConnectionModel<M>(
+        source,
+        target,
+        directedIntersection,
+      ),
+    ] as const
+    : [] as const
+
+  if (direction === 'directed') {
+    return directed
+  }
+  return [
+    ...directed,
+    ...findConnection(target, source, 'directed'),
+  ] as const
+}
+
+/**
+ * Resolve all connections between element and others
+ * By default, look for both directions.
+ *
+ * @default direction both
+ */
+export function findConnectionsBetween<M extends AnyAux>(
+  element: DeploymentElementModel<M>,
+  others: Iterable<DeploymentElementModel<NoInfer<M>>>,
+  direction: 'directed' | 'both' = 'both',
+): readonly DeploymentConnectionModel<M>[] {
+  if (element.allIncoming.isEmpty && element.allOutgoing.isEmpty) {
+    return []
+  }
+
+  // We separate resolved connection,
+  // because we want return outgoing first
+  const outgoing = [] as DeploymentConnectionModel<M>[]
+  const incoming = [] as DeploymentConnectionModel<M>[]
+  for (const _other of others) {
+    if (element === _other) {
+      continue
+    }
+    for (const found of findConnection(element, _other, direction)) {
+      if (found.source === element) {
+        outgoing.push(found)
+      } else {
+        incoming.push(found)
+      }
+    }
+  }
+  return [
+    ...outgoing,
+    ...incoming,
+  ]
+}
+
+/**
+ * Resolve all connections within a given set of elements
+ */
+export function findConnectionsWithin<M extends AnyAux>(
+  elements: Iterable<DeploymentElementModel<M>>,
+): readonly DeploymentConnectionModel<M>[] {
+  return [...elements].reduce((acc, el, index, array) => {
+    // skip for last element
+    if (index === array.length - 1) {
+      return acc
+    }
+    acc.push(
+      ...findConnectionsBetween(el, array.slice(index + 1), 'both'),
+    )
+    return acc
+  }, [] as DeploymentConnectionModel<M>[])
+}

package/src/model/connection/deployment/index.ts

@@ -0,0 +1,8 @@
+export { Connection } from '../Connection'
+export { DeploymentConnectionModel } from './DeploymentConnectionModel'
+
+export {
+  findConnection,
+  findConnectionsBetween,
+  findConnectionsWithin,
+} from './find'

package/src/model/connection/index.ts

@@ -0,0 +1,22 @@
+export { Connection } from './Connection'
+export { DeploymentConnectionModel } from './deployment/DeploymentConnectionModel'
+export { ConnectionModel } from './model/ConnectionModel'
+export {
+  differenceConnections,
+  findAscendingConnections,
+  findDeepestNestedConnection,
+  findDescendantConnections,
+  hasSameSource,
+  hasSameSourceTarget,
+  hasSameTarget,
+  isAnyInOut,
+  isIncoming,
+  isNestedConnection,
+  isOutgoing,
+  mergeConnections,
+  sortConnectionsByBoundaryHierarchy,
+  sortDeepestFirst,
+} from './ops'
+
+export * as deployment from './deployment/find'
+export * as model from './model/find'

package/src/model/connection/model/ConnectionModel.ts

@@ -0,0 +1,157 @@
+import { isNot } from 'remeda'
+import { invariant } from '../../../errors'
+import { customInspectSymbol } from '../../../utils/const'
+import { ifilter, isome } from '../../../utils/iterable'
+import { difference, equals, intersection, union } from '../../../utils/set'
+import { stringHash } from '../../../utils/string-hash'
+import type { ElementModel } from '../../ElementModel'
+import type { RelationshipModel } from '../../RelationModel'
+import type { AnyAux } from '../../types'
+import type { Connection } from '../Connection'
+import { hasSameSourceTarget } from '../ops'
+import { findConnection } from './find'
+
+/**
+ * Connection refers to any relationships between two elements,
+ * both direct and implicit ones (between their nested elements).
+ *
+ * Merges relationships together to an single edge on the diagram.
+ */
+export class ConnectionModel<M extends AnyAux = AnyAux> implements Connection<ElementModel<M>, M['EdgeId']> {
+  public readonly id: M['EdgeId']
+
+  constructor(
+    public readonly source: ElementModel<M>,
+    public readonly target: ElementModel<M>,
+    public readonly relations: ReadonlySet<RelationshipModel<M>> = new Set(),
+  ) {
+    this.id = stringHash(`model:${source.id}:${target.id}`) as M['EdgeId']
+  }
+
+  private _boundary: ElementModel<M> | null | undefined
+  /**
+   * Common ancestor of the source and target elements.
+   * Represents the boundary of the connection.
+   */
+  get boundary(): ElementModel<M> | null {
+    return this._boundary ??= this.source.commonAncestor(this.target)
+  }
+
+  /**
+   * Human readable expression of the connection
+   * Mostly used for testing and debugging
+   */
+  get expression(): string {
+    return `${this.source.id} -> ${this.target.id}`
+  }
+
+  /**
+   * Returns true if only includes relations between the source and target elements.
+   */
+  get isDirect(): boolean {
+    return this.nonEmpty() && !this.isImplicit
+  }
+
+  /**
+   * Returns true if includes relations between nested elements of the source and target elements.
+   */
+  get isImplicit(): boolean {
+    return this.nonEmpty() && isome(this.relations, isNot(hasSameSourceTarget(this)))
+  }
+
+  get directRelations(): ReadonlySet<RelationshipModel<M>> {
+    return new Set(ifilter(this.relations, hasSameSourceTarget(this)))
+  }
+
+  nonEmpty(): boolean {
+    return this.relations.size > 0
+  }
+
+  mergeWith(other: ConnectionModel<M>) {
+    invariant(this.source.id === other.source.id, 'Cannot merge connections with different sources')
+    invariant(this.target.id === other.target.id, 'Cannot merge connections with different targets')
+    return new ConnectionModel(
+      this.source,
+      this.target,
+      union(this.relations, other.relations),
+    )
+  }
+
+  difference(other: ConnectionModel<M>) {
+    return new ConnectionModel(
+      this.source,
+      this.target,
+      difference(this.relations, other.relations),
+    )
+  }
+
+  intersect(other: ConnectionModel<M>) {
+    invariant(other instanceof ConnectionModel, 'Cannot intersect connection with different type')
+    return new ConnectionModel(
+      this.source,
+      this.target,
+      intersection(this.relations, other.relations),
+    )
+  }
+
+  equals(other: Connection): boolean {
+    invariant(other instanceof ConnectionModel, 'Cannot merge connection with different type')
+    return this.id === other.id
+      && this.source.id === other.source.id
+      && this.target.id === other.target.id
+      && equals(this.relations, other.relations)
+  }
+
+  /**
+   * Returns a new instance with the updated relations.
+   *
+   * @param relations - A readonly set of `RelationshipModel` instances representing the new relations.
+   * @returns A new `ConnectionModel` instance with the updated relations.
+   */
+  update(relations: ReadonlySet<RelationshipModel<M>>): ConnectionModel<M> {
+    return new ConnectionModel(
+      this.source,
+      this.target,
+      relations,
+    )
+  }
+
+  [customInspectSymbol](
+    // @ts-ignore
+    depth,
+    // @ts-ignore
+    inspectOptions,
+    // @ts-ignore
+    inspect,
+  ) {
+    const asString = this.toString()
+
+    // Trick so that node displays the name of the constructor
+    Object.defineProperty(asString, 'constructor', {
+      value: ConnectionModel,
+      enumerable: false,
+    })
+
+    return asString
+  }
+
+  toString() {
+    return [
+      this.expression,
+      this.relations.size ? '  relations:' : '  relations: [ ]',
+      ...[...this.relations].map(c => '    ' + c.expression),
+    ].join('\n')
+  }
+
+  /**
+   * Creates a new connection with reversed direction (target becomes source and vice versa)
+   * @param search - When true, attempts to find an existing connection between the reversed nodes
+   */
+  reversed(search = false): ConnectionModel<M> {
+    if (!search) {
+      return new ConnectionModel(this.target, this.source)
+    }
+    const [found] = findConnection(this.target, this.source, 'directed')
+    return found ?? new ConnectionModel(this.target, this.source, new Set())
+  }
+}

package/src/model/connection/model/find.ts

@@ -0,0 +1,117 @@
+import { isSameHierarchy } from '../../../utils/fqn'
+import { intersection } from '../../../utils/set'
+import type { ElementModel } from '../../ElementModel'
+import type { AnyAux } from '../../types'
+import { ConnectionModel } from './ConnectionModel'
+
+/**
+ * Resolve connection from source to target
+ *
+ * @param direction - if 'both', also returns connection from target to source
+ * @default `directed`
+ */
+export function findConnection<M extends AnyAux>(
+  source: ElementModel<M>,
+  target: ElementModel<M>,
+  direction: 'directed' | 'both' = 'directed',
+):
+  | [ConnectionModel<M>, ConnectionModel<M>]
+  | [ConnectionModel<M>]
+  | []
+{
+  if (source === target) {
+    return []
+  }
+  if (isSameHierarchy(source, target)) {
+    return []
+  }
+
+  const directedIntersection = intersection(source.allOutgoing, target.allIncoming)
+
+  const directed = directedIntersection.size > 0
+    ? new ConnectionModel(
+      source,
+      target,
+      directedIntersection,
+    )
+    : null
+
+  if (direction === 'directed') {
+    return directed ? [directed] : []
+  }
+
+  const reverseIntersection = intersection(source.allIncoming, target.allOutgoing)
+  const reverse = reverseIntersection.size > 0
+    ? new ConnectionModel(
+      target,
+      source,
+      reverseIntersection,
+    )
+    : null
+
+  if (directed && reverse) {
+    return [directed, reverse]
+  }
+  if (directed) {
+    return [directed]
+  }
+  if (reverse) {
+    return [reverse]
+  }
+
+  return []
+}
+
+/**
+ * Resolve all connections between element and others
+ * @param direction - if 'directed', only look for outgoing connections from the element to others
+ * @default `both`
+ */
+export function findConnectionsBetween<M extends AnyAux>(
+  element: ElementModel<M>,
+  others: Iterable<ElementModel<NoInfer<M>>>,
+  direction: 'directed' | 'both' = 'both',
+): readonly ConnectionModel<M>[] {
+  if (element.allIncoming.size === 0 && element.allOutgoing.size === 0) {
+    return []
+  }
+
+  // We separate resolved connection,
+  // because we want return outgoing first
+  const outgoing = [] as ConnectionModel<M>[]
+  const incoming = [] as ConnectionModel<M>[]
+  for (const _other of others) {
+    if (element === _other) {
+      continue
+    }
+    for (const found of findConnection(element, _other, direction)) {
+      if (found.source === element) {
+        outgoing.push(found)
+      } else {
+        incoming.push(found)
+      }
+    }
+  }
+  return [
+    ...outgoing,
+    ...incoming,
+  ]
+}
+
+/**
+ * Resolve all connections within a given set of elements
+ */
+export function findConnectionsWithin<M extends AnyAux>(
+  elements: Iterable<ElementModel<M>>,
+): readonly ConnectionModel<M>[] {
+  return [...elements].reduce((acc, el, index, array) => {
+    // skip for last element
+    if (index === array.length - 1) {
+      return acc
+    }
+    acc.push(
+      ...findConnectionsBetween(el, array.slice(index + 1), 'both'),
+    )
+    return acc
+  }, [] as ConnectionModel<M>[])
+}

package/src/model/connection/model/index.ts

@@ -0,0 +1,8 @@
+export { Connection } from '../Connection'
+export { ConnectionModel } from './ConnectionModel'
+
+export {
+  findConnection,
+  findConnectionsBetween,
+  findConnectionsWithin,
+} from './find'