@likec4/core 1.18.0 → 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.ts → deployment/find.ts}

@@ -1,12 +1,8 @@
-import { isSameHierarchy } from '../../utils/fqn'
-import { type DeploymentElementModel } from '../DeploymentElementModel'
-import type { AnyAux } from '../types'
+import { isSameHierarchy } from '../../../utils'
+import type { DeploymentElementModel } from '../../DeploymentElementModel'
+import type { AnyAux } from '../../types'
 import { DeploymentConnectionModel } from './DeploymentConnectionModel'
 
-export { mergeConnections } from './model'
-
-export { DeploymentConnectionModel }
-
 /**
  * Resolve connection from source to target
  * If direction is `both`, also look for reverse connection
@@ -16,14 +12,14 @@ export { DeploymentConnectionModel }
 export function findConnection<M extends AnyAux>(
   source: DeploymentElementModel<M>,
   target: DeploymentElementModel<NoInfer<M>>,
-  direction: 'directed'
+  direction: 'directed',
 ):
   | readonly [DeploymentConnectionModel<M>]
   | readonly []
 export function findConnection<M extends AnyAux>(
   source: DeploymentElementModel<M>,
   target: DeploymentElementModel<NoInfer<M>>,
-  direction: 'both'
+  direction: 'both',
 ):
   | readonly [DeploymentConnectionModel<M>, DeploymentConnectionModel<M>]
   | readonly [DeploymentConnectionModel<M>]
@@ -31,7 +27,7 @@ export function findConnection<M extends AnyAux>(
 export function findConnection<M extends AnyAux>(
   source: DeploymentElementModel<M>,
   target: DeploymentElementModel<NoInfer<M>>,
-  direction?: 'directed' | 'both'
+  direction?: 'directed' | 'both',
 ):
   | readonly [DeploymentConnectionModel<M>, DeploymentConnectionModel<M>]
   | readonly [DeploymentConnectionModel<M>]
@@ -39,7 +35,7 @@ export function findConnection<M extends AnyAux>(
 export function findConnection<M extends AnyAux>(
   source: DeploymentElementModel<M>,
   target: DeploymentElementModel<NoInfer<M>>,
-  direction: 'directed' | 'both' = 'directed'
+  direction: 'directed' | 'both' = 'directed',
 ) {
   if (source === target) {
     return []
@@ -54,8 +50,8 @@ export function findConnection<M extends AnyAux>(
       new DeploymentConnectionModel<M>(
         source,
         target,
-        directedIntersection
-      )
+        directedIntersection,
+      ),
     ] as const
     : [] as const
 
@@ -64,7 +60,7 @@ export function findConnection<M extends AnyAux>(
   }
   return [
     ...directed,
-    ...findConnection(target, source, 'directed')
+    ...findConnection(target, source, 'directed'),
   ] as const
 }
 
@@ -77,7 +73,7 @@ export function findConnection<M extends AnyAux>(
 export function findConnectionsBetween<M extends AnyAux>(
   element: DeploymentElementModel<M>,
   others: Iterable<DeploymentElementModel<NoInfer<M>>>,
-  direction: 'directed' | 'both' = 'both'
+  direction: 'directed' | 'both' = 'both',
 ): readonly DeploymentConnectionModel<M>[] {
   if (element.allIncoming.isEmpty && element.allOutgoing.isEmpty) {
     return []
@@ -101,7 +97,7 @@ export function findConnectionsBetween<M extends AnyAux>(
   }
   return [
     ...outgoing,
-    ...incoming
+    ...incoming,
   ]
 }
 
@@ -109,7 +105,7 @@ export function findConnectionsBetween<M extends AnyAux>(
  * Resolve all connections within a given set of elements
  */
 export function findConnectionsWithin<M extends AnyAux>(
-  elements: Iterable<DeploymentElementModel<M>>
+  elements: Iterable<DeploymentElementModel<M>>,
 ): readonly DeploymentConnectionModel<M>[] {
   return [...elements].reduce((acc, el, index, array) => {
     // skip for last element
@@ -117,7 +113,7 @@ export function findConnectionsWithin<M extends AnyAux>(
       return acc
     }
     acc.push(
-      ...findConnectionsBetween(el, array.slice(index + 1), 'both')
+      ...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.ts → model/find.ts}

@@ -1,36 +1,23 @@
-import { isSameHierarchy } from '../../utils/fqn'
-import { intersection } from '../../utils/set'
-import type { ElementModel } from '../ElementModel'
-import type { AnyAux } from '../types'
-import { type Connection, ConnectionModel } from './ConnectionModel'
-
-export function mergeConnections<C extends Connection<any, any>>(
-  connections: readonly C[]
-): C[] {
-  const map = new Map<C['id'], C>()
-  for (const conn of connections) {
-    const existing = map.get(conn.id)
-    if (existing) {
-      map.set(conn.id, existing.mergeWith(conn) as any)
-    } else {
-      map.set(conn.id, conn)
-    }
-  }
-  return [...map.values()]
-}
+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
- * If direction is `both`, also look for reverse connection
+ *
+ * @param direction - if 'both', also returns connection from target to source
+ * @default `directed`
  */
 export function findConnection<M extends AnyAux>(
   source: ElementModel<M>,
-  target: ElementModel<NoInfer<M>>,
-  direction: 'directed' | 'both' = 'directed'
+  target: ElementModel<M>,
+  direction: 'directed' | 'both' = 'directed',
 ):
-  | readonly [ConnectionModel<M>, ConnectionModel<M>]
-  | readonly [ConnectionModel<M>]
-  | readonly []
+  | [ConnectionModel<M>, ConnectionModel<M>]
+  | [ConnectionModel<M>]
+  | []
 {
   if (source === target) {
     return []
@@ -42,41 +29,48 @@ export function findConnection<M extends AnyAux>(
   const directedIntersection = intersection(source.allOutgoing, target.allIncoming)
 
   const directed = directedIntersection.size > 0
-    ? [
-      new ConnectionModel(
-        source,
-        target,
-        directedIntersection
-      )
-    ] as const
-    : [] as const
+    ? new ConnectionModel(
+      source,
+      target,
+      directedIntersection,
+    )
+    : null
 
   if (direction === 'directed') {
-    return directed
+    return directed ? [directed] : []
   }
 
   const reverseIntersection = intersection(source.allIncoming, target.allOutgoing)
   const reverse = reverseIntersection.size > 0
-    ? [
-      new ConnectionModel(
-        target,
-        source,
-        reverseIntersection
-      )
-    ] as const
-    : [] as const
+    ? new ConnectionModel(
+      target,
+      source,
+      reverseIntersection,
+    )
+    : null
+
+  if (directed && reverse) {
+    return [directed, reverse]
+  }
+  if (directed) {
+    return [directed]
+  }
+  if (reverse) {
+    return [reverse]
+  }
 
-  return [...directed, ...reverse] as const
+  return []
 }
 
 /**
  * Resolve all connections between element and others
- * By default, look for both directions.
+ * @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'
+  direction: 'directed' | 'both' = 'both',
 ): readonly ConnectionModel<M>[] {
   if (element.allIncoming.size === 0 && element.allOutgoing.size === 0) {
     return []
@@ -100,7 +94,7 @@ export function findConnectionsBetween<M extends AnyAux>(
   }
   return [
     ...outgoing,
-    ...incoming
+    ...incoming,
   ]
 }
 
@@ -108,7 +102,7 @@ export function findConnectionsBetween<M extends AnyAux>(
  * Resolve all connections within a given set of elements
  */
 export function findConnectionsWithin<M extends AnyAux>(
-  elements: Iterable<ElementModel<M>>
+  elements: Iterable<ElementModel<M>>,
 ): readonly ConnectionModel<M>[] {
   return [...elements].reduce((acc, el, index, array) => {
     // skip for last element
@@ -116,7 +110,7 @@ export function findConnectionsWithin<M extends AnyAux>(
       return acc
     }
     acc.push(
-      ...findConnectionsBetween(el, array.slice(index + 1), 'both')
+      ...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'