@likec4/core 1.31.0 → 1.32.1

package/src/model/ElementModel.ts

@@ -1,45 +1,41 @@
-import { isTruthy } from 'remeda'
+import { isTruthy, unique } from 'remeda'
 import type { SetRequired } from 'type-fest'
-import type { IteratorLike } from '../types/_common'
+import type { Any, AnyAux, Color, IteratorLike } from '../types'
 import {
   type Element as C4Element,
-  type ElementKind as C4ElementKind,
   type ElementShape as C4ElementShape,
   type ElementStyle,
+  type IconUrl,
   type Link,
+  type ProjectId,
   DefaultElementShape,
   DefaultShapeSize,
   DefaultThemeColor,
-} from '../types/element'
-import {
-  type IconUrl,
-  type ProjectId,
-  type Tag as C4Tag,
   splitGlobalFqn,
-} from '../types/scalars'
-import type { ThemeColor } from '../types/theme'
-import { commonAncestor, hierarchyLevel, isAncestor, sortNaturalByFqn } from '../utils'
+} from '../types'
+import * as aux from '../types/aux'
+import { commonAncestor, hierarchyLevel, ihead, isAncestor, memoizeProp, sortNaturalByFqn } from '../utils'
 import { type DeployedInstancesIterator } from './DeploymentElementModel'
 import type { LikeC4Model } from './LikeC4Model'
 import type { RelationshipModel, RelationshipsIterator } from './RelationModel'
-import type { AnyAux, IncomingFilter, OutgoingFilter } from './types'
-import type { LikeC4ViewModel, ViewsIterator } from './view/LikeC4ViewModel'
+import type { $ViewWithType, IncomingFilter, OutgoingFilter } from './types'
+import type { LikeC4ViewModel } from './view/LikeC4ViewModel'
 
 export type ElementsIterator<M extends AnyAux> = IteratorLike<ElementModel<M>>
 
-export class ElementModel<M extends AnyAux = AnyAux> {
-  readonly id: M['Fqn']
-  readonly _literalId: M['Element']
+export class ElementModel<A extends AnyAux = Any> {
+  readonly id: aux.Fqn<A>
+  readonly _literalId: aux.ElementId<A>
   readonly hierarchyLevel: number
 
   readonly imported: null | {
     from: ProjectId
-    fqn: string
+    fqn: aux.Fqn<A>
   }
 
   constructor(
-    public readonly $model: LikeC4Model<M>,
-    public readonly $element: C4Element,
+    public readonly $model: LikeC4Model<A>,
+    public readonly $element: C4Element<A>,
   ) {
     this.id = this.$element.id
     this._literalId = this.$element.id
@@ -56,11 +52,11 @@ export class ElementModel<M extends AnyAux = AnyAux> {
     }
   }
 
-  get parent(): ElementModel<M> | null {
+  get parent(): ElementModel<A> | null {
     return this.$model.parent(this)
   }
 
-  get kind(): C4ElementKind {
+  get kind(): aux.ElementKind<A> {
     return this.$element.kind
   }
 
@@ -68,16 +64,25 @@ export class ElementModel<M extends AnyAux = AnyAux> {
     return this.$element.shape ?? DefaultElementShape
   }
 
-  get color(): ThemeColor {
-    return this.$element.color as ThemeColor ?? DefaultThemeColor
+  get color(): Color {
+    return this.$element.color as Color ?? DefaultThemeColor
   }
 
   get icon(): IconUrl | null {
     return this.$element.icon ?? null
   }
 
-  get tags(): ReadonlyArray<C4Tag> {
-    return this.$element.tags ?? []
+  /**
+   * Returns all tags of the element.
+   * It includes tags from the element and its kind.
+   */
+  get tags(): aux.Tags<A> {
+    return memoizeProp(this, Symbol.for('tags'), () => {
+      return unique([
+        ...(this.$element.tags ?? []),
+        ...(this.$model.specification.elements[this.$element.kind]?.tags ?? []),
+      ] as aux.Tags<A>)
+    })
   }
 
   get title(): string {
@@ -85,19 +90,19 @@ export class ElementModel<M extends AnyAux = AnyAux> {
   }
 
   get description(): string | null {
-    return this.$element.description
+    return this.$element.description ?? null
   }
 
   get technology(): string | null {
-    return this.$element.technology
+    return this.$element.technology ?? null
   }
 
   get links(): ReadonlyArray<Link> {
     return this.$element.links ?? []
   }
 
-  get defaultView(): LikeC4ViewModel<M> | null {
-    return this.scopedViews().next().value ?? null
+  get defaultView(): LikeC4ViewModel<A, $ViewWithType<A, 'element'> & { viewOf: aux.StrictFqn<A> }> | null {
+    return memoizeProp(this, Symbol.for('defaultView'), () => ihead(this.scopedViews()) ?? null)
   }
 
   get isRoot(): boolean {
@@ -111,11 +116,11 @@ export class ElementModel<M extends AnyAux = AnyAux> {
     }
   }
 
-  public isAncestorOf(another: ElementModel<M>): boolean {
+  public isAncestorOf(another: ElementModel<A>): boolean {
     return isAncestor(this, another)
   }
 
-  public isDescendantOf(another: ElementModel<M>): boolean {
+  public isDescendantOf(another: ElementModel<A>): boolean {
     return isAncestor(another, this)
   }
 
@@ -123,26 +128,26 @@ export class ElementModel<M extends AnyAux = AnyAux> {
    * Get all ancestor elements (i.e. parent, parent’s parent, etc.)
    * (from closest to root)
    */
-  public ancestors(): ElementsIterator<M> {
+  public ancestors(): ElementsIterator<A> {
     return this.$model.ancestors(this)
   }
 
   /**
    * Returns the common ancestor of this element and another element.
    */
-  public commonAncestor(another: ElementModel<M>): ElementModel<M> | null {
+  public commonAncestor(another: ElementModel<A>): ElementModel<A> | null {
     const common = commonAncestor(this.id, another.id)
     return common ? this.$model.element(common) : null
   }
 
-  public children(): ReadonlySet<ElementModel<M>> {
+  public children(): ReadonlySet<ElementModel<A>> {
     return this.$model.children(this)
   }
 
   /**
    * Get all descendant elements (i.e. children, children’s children, etc.)
    */
-  public descendants(sort?: 'asc' | 'desc'): ElementsIterator<M> {
+  public descendants(sort?: 'asc' | 'desc'): ElementsIterator<A> {
     if (sort) {
       const sorted = sortNaturalByFqn([...this.$model.descendants(this)], sort)
       return sorted[Symbol.iterator]()
@@ -153,15 +158,15 @@ export class ElementModel<M extends AnyAux = AnyAux> {
   /**
    * Get all sibling (i.e. same parent)
    */
-  public siblings(): ElementsIterator<M> {
+  public siblings(): ElementsIterator<A> {
     return this.$model.siblings(this)
   }
 
   /**
    * Resolve siblings of the element and its ancestors
-   *  (from closest to root)
+   * (from closest parent to root)
    */
-  public *ascendingSiblings(): ElementsIterator<M> {
+  public *ascendingSiblings(): ElementsIterator<A> {
     yield* this.siblings()
     for (const ancestor of this.ancestors()) {
       yield* ancestor.siblings()
@@ -173,7 +178,7 @@ export class ElementModel<M extends AnyAux = AnyAux> {
    * Resolve siblings of the element and its ancestors
    *  (from root to closest)
    */
-  public *descendingSiblings(): ElementsIterator<M> {
+  public *descendingSiblings(): ElementsIterator<A> {
     for (const ancestor of [...this.ancestors()].reverse()) {
       yield* ancestor.siblings()
     }
@@ -181,11 +186,11 @@ export class ElementModel<M extends AnyAux = AnyAux> {
     return
   }
 
-  public incoming(filter: IncomingFilter = 'all'): RelationshipsIterator<M> {
+  public incoming(filter: IncomingFilter = 'all'): RelationshipsIterator<A> {
     return this.$model.incoming(this, filter)
   }
-  public *incomers(filter: IncomingFilter = 'all'): ElementsIterator<M> {
-    const unique = new Set<M['Fqn']>()
+  public *incomers(filter: IncomingFilter = 'all'): ElementsIterator<A> {
+    const unique = new Set<aux.StrictFqn<A>>()
     for (const r of this.incoming(filter)) {
       if (unique.has(r.source.id)) {
         continue
@@ -195,11 +200,11 @@ export class ElementModel<M extends AnyAux = AnyAux> {
     }
     return
   }
-  public outgoing(filter: OutgoingFilter = 'all'): RelationshipsIterator<M> {
+  public outgoing(filter: OutgoingFilter = 'all'): RelationshipsIterator<A> {
     return this.$model.outgoing(this, filter)
   }
-  public *outgoers(filter: OutgoingFilter = 'all'): ElementsIterator<M> {
-    const unique = new Set<M['Fqn']>()
+  public *outgoers(filter: OutgoingFilter = 'all'): ElementsIterator<A> {
+    const unique = new Set<aux.StrictFqn<A>>()
     for (const r of this.outgoing(filter)) {
       if (unique.has(r.target.id)) {
         continue
@@ -210,65 +215,71 @@ export class ElementModel<M extends AnyAux = AnyAux> {
     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 allOutgoing(): ReadonlySet<RelationshipModel<A>> {
+    return memoizeProp(this, Symbol.for('allOutgoing'), () => new Set(this.outgoing()))
   }
 
-  public get allIncoming(): ReadonlySet<RelationshipModel<M>> {
-    this.cachedIncoming ??= new Set(this.incoming())
-    return this.cachedIncoming
+  public get allIncoming(): ReadonlySet<RelationshipModel<A>> {
+    return memoizeProp(this, Symbol.for('allIncoming'), () => new Set(this.incoming()))
   }
 
   /**
    * 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
+  public views(): ReadonlySet<LikeC4ViewModel<A>> {
+    return memoizeProp(this, Symbol.for('views'), () => {
+      const views = new Set<LikeC4ViewModel<A>>()
+      for (const view of this.$model.views()) {
+        if (view.includesElement(this.id)) {
+          views.add(view)
+        }
       }
-    }
-    return
+      return views
+    })
   }
 
   /**
    * 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
+  public scopedViews(): ReadonlySet<
+    LikeC4ViewModel<A, $ViewWithType<A, 'element'> & { viewOf: aux.StrictFqn<A> }>
+  > {
+    return memoizeProp(this, Symbol.for('scopedViews'), () => {
+      const views = new Set<LikeC4ViewModel<A, $ViewWithType<A, 'element'> & { viewOf: aux.StrictFqn<A> }>>()
+      for (const vm of this.$model.views()) {
+        if (vm.isScopedElementView() && vm.viewOf.id === this.id) {
+          views.add(vm)
+        }
       }
-    }
-    return
+      return views
+    })
   }
 
   /**
    * @returns true if the element is deployed
    */
   public isDeployed(): boolean {
-    return isTruthy(this.deployments().next().value)
+    return isTruthy(ihead(this.deployments()))
   }
 
-  public deployments(): DeployedInstancesIterator<M> {
+  public deployments(): DeployedInstancesIterator<A> {
     return this.$model.deployment.instancesOf(this)
   }
 
-  public getMetadata(): Record<string, string>
-  public getMetadata(field: string): string | undefined
-  public getMetadata(field?: string) {
+  public getMetadata(): aux.Metadata<A>
+  public getMetadata(field: aux.MetadataKey<A>): string | undefined
+  public getMetadata(field?: aux.MetadataKey<A>) {
     if (field) {
       return this.$element.metadata?.[field]
     }
     return this.$element.metadata ?? {}
   }
-}
 
-export function isElementModel<M extends AnyAux = AnyAux>(element: any): element is ElementModel<M> {
-  return element instanceof ElementModel
+  /**
+   * Checks if the element has the given tag.
+   */
+  public isTagged(tag: aux.LooseTag<A>): boolean {
+    return this.tags.includes(tag as aux.Tag<A>)
+  }
 }