@likec4/core 1.17.1 → 1.18.0

package/src/model/DeploymentModel.ts

@@ -0,0 +1,364 @@
+import DefaultMap from 'mnemonist/default-map'
+import { values } from 'remeda'
+import type { LiteralUnion } from 'type-fest'
+import { invariant, nonNullable } from '../errors'
+import {
+  type AnyLikeC4Model,
+  type ComputedDeploymentView,
+  DeploymentElement,
+  type DeploymentRef,
+  type DeploymentRelation,
+  type Tag as C4Tag
+} from '../types'
+import { ancestorsFqn, parentFqn } from '../utils/fqn'
+import { getOrCreate } from '../utils/getOrCreate'
+import { isString } from '../utils/guards'
+import {
+  DeployedInstanceModel,
+  type DeployedInstancesIterator,
+  DeploymentElementModel,
+  type DeploymentElementsIterator,
+  DeploymentNodeModel,
+  type DeploymentNodesIterator,
+  DeploymentRelationModel,
+  NestedElementOfDeployedInstanceModel
+} from './DeploymentElementModel'
+import type { LikeC4Model } from './LikeC4Model'
+import { type AnyAux, getId, type IncomingFilter, type IteratorLike, type OutgoingFilter } from './types'
+import type { LikeC4ViewModel } from './view/LikeC4ViewModel'
+
+export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
+  readonly #elements = new Map<M['Deployment'], DeploymentElementModel<M>>()
+  // Parent element for given FQN
+  readonly #parents = new Map<M['Deployment'], DeploymentNodeModel<M>>()
+  // Children elements for given FQN
+  readonly #children = new DefaultMap<M['Deployment'], Set<DeploymentElementModel<M>>>(() => new Set())
+
+  // Keep track of instances of the logical element
+  readonly #instancesOf = new DefaultMap<M['Element'], Set<DeployedInstanceModel<M>>>(() => new Set())
+
+  readonly #rootElements = new Set<DeploymentNodeModel<M>>()
+
+  readonly #relations = new Map<M['RelationId'], DeploymentRelationModel<M>>()
+
+  // Incoming to an element or its descendants
+  readonly #incoming = new DefaultMap<M['Deployment'], Set<DeploymentRelationModel<M>>>(() => new Set())
+
+  // Outgoing from an element or its descendants
+  readonly #outgoing = new DefaultMap<M['Deployment'], Set<DeploymentRelationModel<M>>>(() => new Set())
+
+  // Relationships inside the element, among descendants
+  readonly #internal = new DefaultMap<M['Deployment'], Set<DeploymentRelationModel<M>>>(() => new Set())
+
+  // readonly #views = new Map<ViewID, LikeC4ViewModel<M>>()
+
+  readonly #allTags = new DefaultMap<C4Tag, Set<DeploymentElementModel<M> | DeploymentRelationModel<M>>>(() =>
+    new Set()
+  )
+
+  readonly #nestedElementsOfDeployment = new Map<
+    `${M['Deployment']}@${M['Element']}`,
+    NestedElementOfDeployedInstanceModel<M>
+  >()
+
+  constructor(
+    public readonly $model: LikeC4Model<M>,
+    public readonly $deployments: AnyLikeC4Model['deployments']
+  ) {
+    for (const element of values($deployments.elements)) {
+      const el = this.addElement(element)
+      for (const tag of el.tags) {
+        this.#allTags.get(tag).add(el)
+      }
+      if (el.isInstance()) {
+        this.#instancesOf.get(el.$element.id).add(el)
+      }
+    }
+    for (const relation of values($deployments.relations)) {
+      const el = this.addRelation(relation)
+      for (const tag of el.tags) {
+        this.#allTags.get(tag).add(el)
+      }
+    }
+  }
+
+  public element(el: M['DeploymentOrFqn']): DeploymentElementModel<M> {
+    if (el instanceof DeploymentElementModel) {
+      return el
+    }
+    const id = getId(el)
+    return nonNullable(this.#elements.get(id), `Element ${id} not found`)
+  }
+  public findElement(el: M['Deployment']): DeploymentElementModel<M> | null {
+    return this.#elements.get(el) ?? null
+  }
+
+  public node(el: M['DeploymentOrFqn']): DeploymentNodeModel<M> {
+    const element = this.element(el)
+    invariant(element.isDeploymentNode(), `Element ${element.id} is not a deployment node`)
+    return element
+  }
+  public findNode(el: M['Deployment']): DeploymentNodeModel<M> | null {
+    const element = this.findElement(el)
+    if (!element) {
+      return null
+    }
+    invariant(element.isDeploymentNode(), `Element ${element?.id} is not a deployment node`)
+    return element
+  }
+
+  public instance(el: M['DeploymentOrFqn']): DeployedInstanceModel<M> {
+    const element = this.element(el)
+    invariant(element.isInstance(), `Element ${element.id} is not a deployed instance`)
+    return element
+  }
+  public findInstance(el: M['Deployment']): DeployedInstanceModel<M> | null {
+    const element = this.findElement(el)
+    if (!element) {
+      return null
+    }
+    invariant(element.isInstance(), `Element ${element?.id} is not a deployed instance`)
+    return element
+  }
+
+  /**
+   * Returns the root elements of the model.
+   */
+  public roots(): DeploymentNodesIterator<M> {
+    return this.#rootElements.values()
+  }
+
+  /**
+   * Returns all elements in the model.
+   */
+  public elements(): DeploymentElementsIterator<M> {
+    return this.#elements.values()
+  }
+
+  /**
+   * Returns all elements in the model.
+   */
+  public *nodes(): DeploymentNodesIterator<M> {
+    for (const element of this.#elements.values()) {
+      if (element.isDeploymentNode()) {
+        yield element
+      }
+    }
+    return
+  }
+
+  public *instances(): DeployedInstancesIterator<M> {
+    for (const element of this.#elements.values()) {
+      if (element.isInstance()) {
+        yield element
+      }
+    }
+    return
+  }
+
+  /**
+   * Iterate over all instances of the given logical element.
+   */
+  public *instancesOf(element: M['ElementOrFqn']): DeployedInstancesIterator<M> {
+    const id = getId(element)
+    const instances = this.#instancesOf.get(id)
+    if (instances) {
+      yield* instances
+    }
+    return
+  }
+
+  public deploymentRef(ref: DeploymentRef): DeploymentElementModel<M> | NestedElementOfDeployedInstanceModel<M> {
+    if ('element' in ref) {
+      const { id, element } = ref
+      return getOrCreate(this.#nestedElementsOfDeployment, `${id}@${element}`, () => {
+        return new NestedElementOfDeployedInstanceModel(this.instance(id), this.$model.element(element))
+      })
+    }
+    return this.element(ref)
+  }
+
+  /**
+   * Returns all relationships in the model.
+   */
+  public relationships(): IteratorLike<DeploymentRelationModel<M>> {
+    return this.#relations.values()
+  }
+
+  /**
+   * Returns a specific relationship by its ID.
+   */
+  public relationship(id: M['RelationId']): DeploymentRelationModel<M> {
+    return nonNullable(this.#relations.get(id), `DeploymentRelationModel ${id} not found`)
+  }
+  public findRelationship(id: LiteralUnion<M['RelationId'], string>): DeploymentRelationModel<M> | null {
+    return this.#relations.get(id as M['RelationId']) ?? null
+  }
+
+  /**
+   * Returns all deployment views in the model.
+   */
+  public *views(): IteratorLike<LikeC4ViewModel<M, ComputedDeploymentView>> {
+    for (const view of this.$model.views()) {
+      if (view.isDeploymentView()) {
+        yield view
+      }
+    }
+    return
+  }
+
+  /**
+   * Returns the parent element of given element.
+   * @see ancestors
+   */
+  public parent(element: M['DeploymentOrFqn']): DeploymentNodeModel<M> | null {
+    const id = getId(element)
+    return this.#parents.get(id) || null
+  }
+
+  /**
+   * Get all children of the element (only direct children),
+   * @see descendants
+   */
+  public children(element: M['DeploymentOrFqn']): ReadonlySet<DeploymentElementModel<M>> {
+    const id = getId(element)
+    return this.#children.get(id)
+  }
+
+  /**
+   * Get all sibling (i.e. same parent)
+   */
+  public *siblings(element: M['DeploymentOrFqn']): DeploymentElementsIterator<M> {
+    const id = getId(element)
+    const siblings = this.parent(element)?.children() ?? this.roots()
+    for (const sibling of siblings) {
+      if (sibling.id !== id) {
+        yield sibling
+      }
+    }
+    return
+  }
+
+  /**
+   * Get all ancestor elements (i.e. parent, parent’s parent, etc.)
+   * (from closest to root)
+   */
+  public *ancestors(element: M['DeploymentOrFqn']): DeploymentNodesIterator<M> {
+    let id = isString(element) ? element : element.id
+    let parent
+    while (parent = this.#parents.get(id)) {
+      yield parent
+      id = parent.id
+    }
+    return
+  }
+
+  /**
+   * Get all descendant elements (i.e. children, children’s children, etc.)
+   */
+  public *descendants(element: M['DeploymentOrFqn']): DeploymentElementsIterator<M> {
+    for (const child of this.children(element)) {
+      yield child
+      yield* this.descendants(child.id)
+    }
+    return
+  }
+
+  /**
+   * Incoming relationships to the element and its descendants
+   * @see incomers
+   */
+  public *incoming(
+    element: M['DeploymentOrFqn'],
+    filter: IncomingFilter = 'all'
+  ): IteratorLike<DeploymentRelationModel<M>> {
+    const id = getId(element)
+    for (const rel of this.#incoming.get(id)) {
+      switch (true) {
+        case filter === 'all':
+        case filter === 'direct' && rel.target.id === id:
+        case filter === 'to-descendants' && rel.target.id !== id:
+          yield rel
+          break
+      }
+    }
+    return
+  }
+
+  /**
+   * Outgoing relationships from the element and its descendants
+   * @see outgoers
+   */
+  public *outgoing(
+    element: M['DeploymentOrFqn'],
+    filter: OutgoingFilter = 'all'
+  ): IteratorLike<DeploymentRelationModel<M>> {
+    const id = getId(element)
+    for (const rel of this.#outgoing.get(id)) {
+      switch (true) {
+        case filter === 'all':
+        case filter === 'direct' && rel.source.id === id:
+        case filter === 'from-descendants' && rel.source.id !== id:
+          yield rel
+          break
+      }
+    }
+    return
+  }
+
+  private addElement(element: DeploymentElement) {
+    if (this.#elements.has(element.id)) {
+      throw new Error(`Element ${element.id} already exists`)
+    }
+    const el = DeploymentElement.isDeploymentNode(element)
+      ? new DeploymentNodeModel(this, element)
+      : new DeployedInstanceModel(this, element, this.$model.element(element.element))
+    this.#elements.set(el.id, el)
+    const parentId = parentFqn(el.id)
+    if (parentId) {
+      invariant(this.#elements.has(parentId), `Parent ${parentId} of ${el.id} not found`)
+      this.#parents.set(el.id, this.node(parentId))
+      this.#children.get(parentId).add(el)
+    } else {
+      invariant(el.isDeploymentNode(), `Root element ${el.id} is not a deployment node`)
+      this.#rootElements.add(el)
+    }
+    return el
+  }
+
+  private addRelation(relation: DeploymentRelation) {
+    if (this.#relations.has(relation.id)) {
+      throw new Error(`Relation ${relation.id} already exists`)
+    }
+    const rel = new DeploymentRelationModel(
+      this,
+      relation
+    )
+    this.#relations.set(rel.id, rel)
+    this.#incoming.get(rel.target.id).add(rel)
+    this.#outgoing.get(rel.source.id).add(rel)
+
+    const relParent = rel.boundary?.id ?? null
+    // Process internal relationships
+    if (relParent) {
+      for (const ancestor of [relParent, ...ancestorsFqn(relParent)]) {
+        this.#internal.get(ancestor).add(rel)
+      }
+    }
+    // Process source hierarchy
+    for (const sourceAncestor of ancestorsFqn(rel.source.id)) {
+      if (sourceAncestor === relParent) {
+        break
+      }
+      this.#outgoing.get(sourceAncestor).add(rel)
+    }
+    // Process target hierarchy
+    for (const targetAncestor of ancestorsFqn(rel.target.id)) {
+      if (targetAncestor === relParent) {
+        break
+      }
+      this.#incoming.get(targetAncestor).add(rel)
+    }
+    return rel
+  }
+}

package/src/model/ElementModel.ts

@@ -0,0 +1,195 @@
+import { isTruthy } from 'remeda'
+import {
+  DefaultElementShape,
+  DefaultThemeColor,
+  type Element as C4Element,
+  type ElementKind as C4ElementKind,
+  type ElementShape as C4ElementShape,
+  type Link,
+  type Tag as C4Tag,
+  type ThemeColor
+} from '../types'
+import { commonAncestor } from '../utils'
+import { type DeployedInstancesIterator } from './DeploymentElementModel'
+import type { LikeC4Model } from './LikeC4Model'
+import type { RelationshipModel, RelationshipsIterator } from './RelationModel'
+import type { AnyAux, IncomingFilter, IteratorLike, OutgoingFilter } from './types'
+import type { LikeC4ViewModel, ViewsIterator } from './view/LikeC4ViewModel'
+
+export type ElementsIterator<M extends AnyAux> = IteratorLike<ElementModel<M>>
+
+export class ElementModel<M extends AnyAux> {
+  constructor(
+    public readonly model: LikeC4Model<M>,
+    public readonly $element: C4Element
+  ) {
+  }
+
+  get id(): M['Fqn'] {
+    return this.$element.id
+  }
+
+  get kind(): C4ElementKind {
+    return this.$element.kind
+  }
+
+  get shape(): C4ElementShape {
+    return this.$element.shape ?? DefaultElementShape
+  }
+
+  get color(): ThemeColor {
+    return this.$element.color as ThemeColor ?? DefaultThemeColor
+  }
+
+  get tags(): ReadonlyArray<C4Tag> {
+    return this.$element.tags ?? []
+  }
+
+  get title(): string {
+    return this.$element.title
+  }
+
+  get description(): string | null {
+    return this.$element.description
+  }
+
+  get technology(): string | null {
+    return this.$element.technology
+  }
+
+  get links(): ReadonlyArray<Link> {
+    return this.$element.links ?? []
+  }
+
+  get parent(): ElementModel<M> | null {
+    return this.model.parent(this)
+  }
+
+  get defaultView(): LikeC4ViewModel<M> | null {
+    return this.scopedViews().next().value ?? null
+  }
+
+  /**
+   * Get all ancestor elements (i.e. parent, parent’s parent, etc.)
+   * (from closest to root)
+   */
+  public ancestors(): ElementsIterator<M> {
+    return this.model.ancestors(this)
+  }
+
+  /**
+   * Returns the common ancestor of this element and another element.
+   */
+  public commonAncestor(another: ElementModel<M>): ElementModel<M> | null {
+    const common = commonAncestor(this.id, another.id)
+    return common ? this.model.element(common) : null
+  }
+
+  public children(): ReadonlySet<ElementModel<M>> {
+    return this.model.children(this)
+  }
+
+  /**
+   * Get all descendant elements (i.e. children, children’s children, etc.)
+   */
+  public descendants(): ElementsIterator<M> {
+    return this.model.descendants(this)
+  }
+
+  /**
+   * Get all sibling (i.e. same parent)
+   */
+  public siblings(): ElementsIterator<M> {
+    return this.model.siblings(this)
+  }
+
+  /**
+   * Resolve siblings of the element and its ancestors
+   *  (from closest to root)
+   */
+  public *ascendingSiblings(): ElementsIterator<M> {
+    yield* this.siblings()
+    for (const ancestor of this.ancestors()) {
+      yield* ancestor.siblings()
+    }
+    return
+  }
+
+  public incoming(filter: IncomingFilter = 'all'): RelationshipsIterator<M> {
+    return this.model.incoming(this, filter)
+  }
+  public *incomers(filter: IncomingFilter = 'all'): ElementsIterator<M> {
+    const unique = new Set<M['Fqn']>()
+    for (const r of this.incoming(filter)) {
+      if (unique.has(r.source.id)) {
+        continue
+      }
+      unique.add(r.source.id)
+      yield r.source
+    }
+    return
+  }
+  public outgoing(filter: OutgoingFilter = 'all'): RelationshipsIterator<M> {
+    return this.model.outgoing(this, filter)
+  }
+  public *outgoers(filter: OutgoingFilter = 'all'): ElementsIterator<M> {
+    const unique = new Set<M['Fqn']>()
+    for (const r of this.outgoing(filter)) {
+      if (unique.has(r.target.id)) {
+        continue
+      }
+      unique.add(r.target.id)
+      yield r.target
+    }
+    return
+  }
+
+  protected cachedOutgoing: Set<RelationshipModel<M>> | null = null
+  protected cachedIncoming: Set<RelationshipModel<M>> | null = null
+
+  public get allOutgoing(): ReadonlySet<RelationshipModel<M>> {
+    this.cachedOutgoing ??= new Set(this.outgoing())
+    return this.cachedOutgoing
+  }
+
+  public get allIncoming(): ReadonlySet<RelationshipModel<M>> {
+    this.cachedIncoming ??= new Set(this.incoming())
+    return this.cachedIncoming
+  }
+
+  /**
+   * Iterate over all views that include this element.
+   */
+  public *views(): ViewsIterator<M> {
+    for (const view of this.model.views()) {
+      if (view.includesElement(this.id)) {
+        yield view
+      }
+    }
+    return
+  }
+
+  /**
+   * Iterate over all views that scope this element.
+   * It is possible that element is not included in the view.
+   */
+  public *scopedViews(): ViewsIterator<M> {
+    for (const vm of this.model.views()) {
+      if (vm.isElementView() && vm.$view.viewOf === this.id) {
+        yield vm
+      }
+    }
+    return
+  }
+
+  /**
+   * @returns true if the element is deployed
+   */
+  public isDeployed(): boolean {
+    return isTruthy(this.deployments().next().value)
+  }
+
+  public deployments(): DeployedInstancesIterator<M> {
+    return this.model.deployment.instancesOf(this)
+  }
+}

package/src/model/LikeC4Model.test-d.ts

@@ -0,0 +1,151 @@
+import { expectTypeOf, test } from 'vitest'
+import { Builder } from '../builder'
+import { computeViews } from '../compute-view/compute-view'
+import type { ComputedView, Fqn, ViewId } from '../types'
+import { LikeC4Model } from './LikeC4Model'
+
+test('LikeC4Model.create: should have types', () => {
+  const {
+    model: {
+      model,
+      actor,
+      system,
+      component,
+      relTo
+    },
+    deployment: {
+      deployment,
+      instanceOf,
+      env,
+      vm
+    },
+    views: {
+      deploymentView,
+      views,
+      view,
+      $include
+    },
+    builder
+  } = Builder.forSpecification({
+    elements: {
+      actor: {
+        style: {
+          shape: 'person'
+        }
+      },
+      system: {},
+      component: {}
+    },
+    deployments: {
+      env: {},
+      vm: {}
+    },
+    relationships: {
+      like: {},
+      dislike: {}
+    },
+    tags: ['tag1', 'tag2', 'tag1']
+  })
+
+  const source = builder
+    .with(
+      model(
+        actor('alice'),
+        actor('bob'),
+        system('cloud').with(
+          component('backend').with(
+            component('api'),
+            component('db')
+          ),
+          component('frontend').with(
+            relTo('cloud.backend.api')
+          )
+        )
+      ),
+      deployment(
+        env('prod').with(
+          vm('vm1'),
+          vm('vm2')
+        ),
+        env('dev').with(
+          vm('vm1'),
+          instanceOf('api', 'cloud.backend.api'),
+          vm('vm2')
+        )
+      ),
+      views(
+        view('index', $include('*')),
+        deploymentView('prodview', $include('*'))
+      )
+    )
+    .build()
+
+  const computed = computeViews(source)
+  const m = LikeC4Model.create(computed)
+
+  expectTypeOf(m.Aux.Element).toEqualTypeOf(
+    '' as 'alice' | 'bob' | 'cloud' | 'cloud.backend' | 'cloud.backend.api' | 'cloud.backend.db' | 'cloud.frontend'
+  )
+  expectTypeOf(m.Aux.Fqn).toEqualTypeOf(
+    '' as Fqn<'alice' | 'bob' | 'cloud' | 'cloud.backend' | 'cloud.backend.api' | 'cloud.backend.db' | 'cloud.frontend'>
+  )
+  expectTypeOf(m.Aux.ViewId).toEqualTypeOf(
+    '' as ViewId<'index' | 'prodview'>
+  )
+  expectTypeOf(m.Aux.ViewType).toEqualTypeOf(
+    {} as ComputedView<ViewId<'index' | 'prodview'>>
+  )
+  expectTypeOf(m.Aux.Deployment).toEqualTypeOf(
+    '' as 'prod' | 'dev' | 'prod.vm1' | 'prod.vm2' | 'dev.vm1' | 'dev.vm2' | 'dev.api'
+  )
+  expectTypeOf(m.Aux.DeploymentFqn).toEqualTypeOf(
+    '' as Fqn<'prod' | 'dev' | 'prod.vm1' | 'prod.vm2' | 'dev.vm1' | 'dev.vm2' | 'dev.api'>
+  )
+})
+
+test('LikeC4Model.fromDump: should have types', () => {
+  const m = LikeC4Model.fromDump({
+    specification: {
+      tags: [],
+      elements: {},
+      relationships: {},
+      deployments: {}
+    },
+    elements: {
+      el1: {},
+      el2: {}
+    },
+    relations: {},
+    globals: {
+      predicates: {},
+      dynamicPredicates: {},
+      styles: {}
+    },
+    views: {
+      v1: {},
+      v2: {}
+    },
+    deployments: {
+      elements: {
+        d1: {},
+        d2: {}
+      },
+      relations: {}
+    }
+  })
+  expectTypeOf(m.Aux.Element).toEqualTypeOf(
+    '' as 'el1' | 'el2'
+  )
+  expectTypeOf(m.Aux.Fqn).toEqualTypeOf(
+    '' as Fqn<'el1' | 'el2'>
+  )
+  expectTypeOf(m.Aux.ViewId).toEqualTypeOf(
+    '' as ViewId<'v1' | 'v2'>
+  )
+  expectTypeOf(m.Aux.Deployment).toEqualTypeOf(
+    '' as 'd1' | 'd2'
+  )
+  expectTypeOf(m.Aux.DeploymentFqn).toEqualTypeOf(
+    '' as Fqn<'d1' | 'd2'>
+  )
+})