@likec4/core 1.17.1 → 1.18.0

package/src/model/view/LikeC4ViewModel.ts

@@ -0,0 +1,220 @@
+import { sort } from 'remeda'
+import { nonNullable } from '../../errors'
+import type { Link, Tag } from '../../types/element'
+import {
+  type ComputedDeploymentView,
+  type ComputedDynamicView,
+  type ComputedElementView,
+  type ComputedView,
+  type DiagramView,
+  type EdgeId as C4EdgeId,
+  isDeploymentView,
+  isDynamicView,
+  isElementView,
+  isScopedElementView,
+  type LikeC4View,
+  type NodeId as C4NodeId
+} from '../../types/view'
+import { compareByFqnHierarchically, getOrCreate } from '../../utils'
+import type { ElementModel } from '../ElementModel'
+import type { LikeC4Model } from '../LikeC4Model'
+import { type AnyAux, getId, type IteratorLike } from '../types'
+import { EdgeModel, type EdgesIterator } from './EdgeModel'
+import { NodeModel, type NodesIterator } from './NodeModel'
+
+export type ViewsIterator<M extends AnyAux> = IteratorLike<LikeC4ViewModel<M>>
+
+export class LikeC4ViewModel<M extends AnyAux, V extends ComputedView | DiagramView = M['ViewType']> {
+  readonly #rootnodes = new Set<NodeModel<M, V>>()
+  readonly #nodes = new Map<C4NodeId, NodeModel<M, V>>()
+  readonly #edges = new Map<C4EdgeId, EdgeModel<M, V>>()
+  readonly #includeElements = new Set<M['Element']>()
+  readonly #includeDeployments = new Set<M['Deployment']>()
+  readonly #includeRelations = new Set<M['RelationId']>()
+  readonly #allTags = new Map<Tag, Set<NodeModel<M, V> | EdgeModel<M, V>>>()
+
+  constructor(
+    public readonly $model: LikeC4Model<M>,
+    public readonly $view: V
+  ) {
+    for (const node of sort($view.nodes, compareByFqnHierarchically)) {
+      const el = new NodeModel(this, node)
+      this.#nodes.set(node.id, el)
+      if (!node.parent) {
+        this.#rootnodes.add(el)
+      }
+      if (el.hasDeployment()) {
+        this.#includeDeployments.add(el.deployment.id)
+      }
+      if (el.hasElement()) {
+        this.#includeElements.add(el.element.id)
+      }
+      for (const tag of el.tags) {
+        getOrCreate(this.#allTags, tag, () => new Set()).add(el)
+      }
+    }
+
+    for (const edge of $view.edges) {
+      const edgeModel = new EdgeModel(this, edge, this.node(edge.source), this.node(edge.target))
+      for (const tag of edgeModel.tags) {
+        getOrCreate(this.#allTags, tag, () => new Set()).add(edgeModel)
+      }
+      for (const rel of edge.relations) {
+        this.#includeRelations.add(rel)
+      }
+      this.#edges.set(edge.id, edgeModel)
+    }
+  }
+
+  get __(): NonNullable<M['ViewType']['__']> {
+    return this.$view.__ ?? 'element'
+  }
+
+  get id(): M['ViewId'] {
+    return this.$view.id
+  }
+
+  get title(): string | null {
+    return this.$view.title
+  }
+
+  get tags(): ReadonlyArray<Tag> {
+    return this.$view.tags ?? []
+  }
+
+  get links(): ReadonlyArray<Link> {
+    return this.$view.links ?? []
+  }
+
+  get viewOf(): ElementModel<M> | null {
+    const v = this.$view as LikeC4View
+    if (isScopedElementView(v)) {
+      return this.$model.element(v.viewOf)
+    }
+    return null
+  }
+
+  /**
+   * All tags from nodes and edges.
+   */
+  get includedTags(): ReadonlyArray<Tag> {
+    return [...this.#allTags.keys()]
+  }
+
+  public roots(): NodesIterator<M, V> {
+    return this.#rootnodes.values()
+  }
+
+  /**
+   * Iterate over all nodes that have children.
+   */
+  public *compounds(): NodesIterator<M, V> {
+    for (const node of this.#nodes.values()) {
+      if (node.hasChildren()) {
+        yield node
+      }
+    }
+    return
+  }
+
+  /**
+   * Get node by id.
+   * @throws Error if node is not found.
+   */
+  public node(node: M['NodeOrId']): NodeModel<M, V> {
+    const nodeId = getId(node)
+    return nonNullable(this.#nodes.get(nodeId), `Node ${nodeId} not found in view ${this.$view.id}`)
+  }
+
+  /**
+   * Find node by id.
+   */
+  public findNode(node: M['NodeOrId']): NodeModel<M, V> | null {
+    return this.#nodes.get(getId(node) as C4NodeId) ?? null
+  }
+  /**
+   * Iterate over all nodes.
+   */
+  public nodes(): NodesIterator<M, V> {
+    return this.#nodes.values()
+  }
+
+  /**
+   * Find edge by id.
+   * @param edge Edge or id
+   * @returns EdgeModel
+   */
+  public edge(edge: M['EdgeOrId']): EdgeModel<M, V> {
+    const edgeId = getId(edge) as C4EdgeId
+    return nonNullable(this.#edges.get(edgeId), `Edge ${edgeId} not found in view ${this.$view.id}`)
+  }
+  public findEdge(edge: M['EdgeOrId']): EdgeModel<M, V> | null {
+    return this.#edges.get(getId(edge) as C4EdgeId) ?? null
+  }
+  /**
+   * Iterate over all edges.
+   */
+  public edges(): EdgesIterator<M, V> {
+    return this.#edges.values()
+  }
+
+  /**
+   * Iterate over all edges.
+   */
+  public *edgesWithRelation(relation: M['RelationId']): EdgesIterator<M, V> {
+    for (const edge of this.#edges.values()) {
+      if (edge.includesRelation(relation)) {
+        yield edge
+      }
+    }
+    return
+  }
+
+  /**
+   * Nodes that have references to elements from logical model.
+   */
+  public *elements(): IteratorLike<NodeModel.WithElement<M, V>> {
+    // return this.#nodes.values().filter(node => node.hasElement())
+    for (const node of this.#nodes.values()) {
+      if (node.hasElement()) {
+        yield node
+      }
+    }
+    return
+  }
+
+  public includesElement(elementId: M['Element']): boolean {
+    return this.#includeElements.has(elementId)
+  }
+
+  public includesDeployment(deploymentId: M['Deployment']): boolean {
+    return this.#includeDeployments.has(deploymentId)
+  }
+
+  public includesRelation(relationId: M['RelationId']): boolean {
+    return this.#includeRelations.has(relationId)
+  }
+
+  /**
+   * Below are type guards.
+   */
+  public isComputed(): this is LikeC4ViewModel<M, ComputedView> {
+    return true // Diagram view is a computed view
+  }
+
+  public isDiagram(): this is LikeC4ViewModel<M, DiagramView> {
+    return 'bounds' in this.$view
+  }
+
+  public isElementView(): this is LikeC4ViewModel<M, ComputedElementView> {
+    return isElementView(this.$view as LikeC4View)
+  }
+
+  public isDeploymentView(): this is LikeC4ViewModel<M, ComputedDeploymentView> {
+    return isDeploymentView(this.$view as LikeC4View)
+  }
+
+  public isDynamicView(): this is LikeC4ViewModel<M, ComputedDynamicView> {
+    return isDynamicView(this.$view as LikeC4View)
+  }
+}

package/src/model/view/NodeModel.ts

@@ -0,0 +1,228 @@
+import {
+  type Color as C4Color,
+  ComputedNode,
+  type ComputedView,
+  type DeploymentNodeKind,
+  type DiagramView,
+  ElementKind,
+  type ElementShape as C4ElementShape,
+  type Link,
+  type NodeId,
+  type Tag as C4Tag
+} from '../../types'
+import type { DeployedInstanceModel, DeploymentElementModel } from '../DeploymentElementModel'
+import type { ElementModel } from '../ElementModel'
+import type { AnyAux, IncomingFilter, IteratorLike, OutgoingFilter } from '../types'
+import type { EdgesIterator } from './EdgeModel'
+import type { LikeC4ViewModel } from './LikeC4ViewModel'
+
+export type NodesIterator<M extends AnyAux, V extends ComputedView | DiagramView> = IteratorLike<NodeModel<M, V>>
+
+export namespace NodeModel {
+  export interface WithParent<M extends AnyAux, V extends ComputedView | DiagramView> extends NodeModel<M, V> {
+    parent: NodeModel<M, V>
+  }
+  export interface WithElement<M extends AnyAux, V extends ComputedView | DiagramView> extends NodeModel<M, V> {
+    kind: ElementKind
+    element: ElementModel<M>
+  }
+  export interface WithDeploymentElement<M extends AnyAux, V extends ComputedView | DiagramView>
+    extends NodeModel<M, V>
+  {
+    kind: DeploymentNodeKind
+    deployment: DeploymentElementModel<M>
+  }
+  export interface WithDeployedInstance<M extends AnyAux, V extends ComputedView | DiagramView>
+    extends NodeModel<M, V>
+  {
+    kind: 'instance'
+    element: ElementModel<M>
+    deployment: DeployedInstanceModel<M>
+  }
+
+  export interface IsGroup<M extends AnyAux, V extends ComputedView | DiagramView> extends NodeModel<M, V> {
+    kind: typeof ElementKind.Group
+    element: null
+    deployment: null
+  }
+}
+
+export class NodeModel<M extends AnyAux, V extends ComputedView | DiagramView = M['ViewType']> {
+  constructor(
+    public readonly $view: LikeC4ViewModel<M, V>,
+    public readonly $node: V['nodes'][number]
+  ) {
+  }
+
+  get id(): NodeId {
+    return this.$node.id
+  }
+
+  get title(): string {
+    return this.$node.title
+  }
+
+  get kind(): ElementKind | DeploymentNodeKind | typeof ElementKind.Group | 'instance' {
+    return this.$node.kind as any
+  }
+
+  get description(): string | null {
+    return this.$node.description
+  }
+
+  get technology(): string | null {
+    return this.$node.technology
+  }
+
+  get parent(): NodeModel<M, V> | null {
+    return this.$node.parent ? this.$view.node(this.$node.parent) : null
+  }
+
+  get element(): ElementModel<M> | null {
+    const modelRef = ComputedNode.modelRef(this.$node)
+    return modelRef ? this.$view.$model.element(modelRef) : null
+  }
+
+  get deployment(): DeploymentElementModel<M> | null {
+    const modelRef = ComputedNode.deploymentRef(this.$node)
+    return modelRef ? this.$view.$model.deployment.element(modelRef) : null
+  }
+
+  get shape(): C4ElementShape {
+    return this.$node.shape
+  }
+
+  get color(): C4Color {
+    return this.$node.color
+  }
+
+  get tags(): ReadonlyArray<C4Tag> {
+    return this.$node.tags ?? []
+  }
+
+  get links(): ReadonlyArray<Link> {
+    return this.$node.links ?? []
+  }
+
+  get navigateTo(): LikeC4ViewModel<M> | null {
+    return this.$node.navigateTo ? this.$view.$model.view(this.$node.navigateTo) : null
+  }
+
+  /**
+   * Get all ancestor elements (i.e. parent, parent’s parent, etc.)
+   * (from closest to root)
+   */
+  public *ancestors(): NodesIterator<M, V> {
+    let parent = this.parent
+    while (parent) {
+      yield parent
+      parent = parent.parent
+    }
+    return
+  }
+
+  public *children(): NodesIterator<M, V> {
+    for (const child of this.$node.children) {
+      yield this.$view.node(child)
+    }
+    return
+  }
+
+  public *sublings(): NodesIterator<M, V> {
+    const sublings = this.parent?.children() ?? this.$view.roots()
+    for (const subling of sublings) {
+      if (subling.id !== this.id) {
+        yield subling
+      }
+    }
+    return
+  }
+
+  public *incoming(filter: IncomingFilter = 'all'): EdgesIterator<M, V> {
+    for (const edgeId of this.$node.inEdges) {
+      const edge = this.$view.edge(edgeId)
+      switch (true) {
+        case filter === 'all':
+        case filter === 'direct' && edge.target.id === this.id:
+        case filter === 'to-descendants' && edge.target.id !== this.id:
+          yield edge
+          break
+      }
+    }
+    return
+  }
+
+  public *incomers(filter: IncomingFilter = 'all'): NodesIterator<M, V> {
+    const unique = new Set<NodeId>()
+    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'): EdgesIterator<M, V> {
+    for (const edgeId of this.$node.outEdges) {
+      const edge = this.$view.edge(edgeId)
+      switch (true) {
+        case filter === 'all':
+        case filter === 'direct' && edge.source.id === this.id:
+        case filter === 'from-descendants' && edge.source.id !== this.id:
+          yield edge
+          break
+      }
+    }
+    return
+  }
+
+  public *outgoers(filter: OutgoingFilter = 'all'): NodesIterator<M, V> {
+    const unique = new Set<NodeId>()
+    for (const r of this.outgoing(filter)) {
+      if (unique.has(r.target.id)) {
+        continue
+      }
+      unique.add(r.target.id)
+      yield r.target
+    }
+    return
+  }
+
+  public isDiagramNode(): this is NodeModel<M, DiagramView> {
+    return 'width' in this.$node && 'height' in this.$node
+  }
+
+  public hasChildren(): boolean {
+    return this.$node.children.length > 0
+  }
+
+  public hasParent(): this is NodeModel.WithParent<M, V> {
+    return this.$node.parent !== null
+  }
+
+  /**
+   * Check if this node references to logical model element.
+   */
+  public hasElement(): this is NodeModel.WithElement<M, V> {
+    return ComputedNode.modelRef(this.$node) !== null
+  }
+  /**
+   * Check if this node references to deployment element (Node or Instance).
+   */
+  public hasDeployment(): this is NodeModel.WithDeploymentElement<M, V> {
+    return ComputedNode.deploymentRef(this.$node) !== null
+  }
+  /**
+   * Check if this node references to deployed instance
+   * Deployed instance always references to element and deployment element.
+   */
+  public hasDeployedInstance(): this is NodeModel.WithDeployedInstance<M, V> {
+    return this.hasElement() && this.hasDeployment()
+  }
+
+  public isGroup(): this is NodeModel.IsGroup<M, V> {
+    return ComputedNode.isNodesGroup(this.$node)
+  }
+}

package/src/types/_common.ts

@@ -14,3 +14,5 @@ export interface XYPoint {
   x: number
   y: number
 }
+
+export type KeysOf<T> = keyof T extends infer K extends string ? K : never

package/src/types/deployments.ts

@@ -0,0 +1,237 @@
+import type { MergeExclusive, Simplify, Tagged, UnionToIntersection } from 'type-fest'
+import type { IconUrl, NonEmptyArray } from './_common'
+import type { ElementShape, ElementStyle, Fqn, Link, Tag } from './element'
+import type { RelationId, RelationshipArrowType, RelationshipKind, RelationshipLineType } from './relation'
+import type { Color } from './theme'
+import type { ViewId } from './view'
+
+export type DeploymentNodeKind<Kinds extends string = string> = Tagged<Kinds, 'DeploymentNodeKind'>
+
+export type PhysicalElementStyle = ElementStyle & {
+  readonly icon?: IconUrl
+  readonly shape?: ElementShape
+  readonly color?: Color
+}
+
+export interface DeploymentNodeKindSpecification {
+  readonly technology?: string
+  readonly notation?: string
+  readonly style: PhysicalElementStyle
+}
+
+export interface DeploymentNode {
+  // Full-qualified-name for Deployment model
+  readonly id: Fqn
+  readonly kind: DeploymentNodeKind
+  readonly title: string
+  readonly description?: string | null
+  readonly technology?: string | null
+  readonly tags?: NonEmptyArray<Tag> | null
+  readonly links?: NonEmptyArray<Link> | null
+  readonly style?: PhysicalElementStyle
+  readonly notation?: string
+  readonly metadata?: Record<string, string>
+}
+
+export interface DeployedInstance {
+  /**
+   * Format: `<DeploymentNode Fqn>.<Instance Id>`
+   * i.e parent fqn is deployment target
+   */
+  readonly id: Fqn
+  readonly element: Fqn
+  readonly title?: string
+  readonly description?: string | null
+  readonly technology?: string | null
+  readonly tags?: NonEmptyArray<Tag> | null
+  readonly links?: NonEmptyArray<Link> | null
+  readonly style?: PhysicalElementStyle
+  readonly notation?: string
+  readonly metadata?: Record<string, string>
+}
+
+export type DeploymentElement = Simplify<MergeExclusive<DeploymentNode, DeployedInstance>>
+
+export namespace DeploymentElement {
+  export const isDeploymentNode = (el: DeploymentElement): el is DeploymentNode => {
+    return 'kind' in el && !('element' in el)
+  }
+  export const isInstance = (el: DeploymentElement): el is DeployedInstance => {
+    return 'element' in el && !('kind' in el)
+  }
+}
+
+export interface DeploymentRef {
+  // Reference to DeploymentNode or DeployedInstance
+  readonly id: Fqn
+  // Reference to element within DeployedInstance
+  readonly element?: Fqn
+}
+
+// export namespace DeploymentRef {
+//   export interface Node {
+//     readonly id: Fqn
+//   }
+//   export interface Instance {
+//     readonly id: Fqn
+//     readonly element?: Fqn
+//   }
+//   export interface LogicalElement {
+//     readonly element: Fqn
+//   }
+
+//   export const isDeploymentElement = (ref: DeploymentRef): ref is Node | Instance => {
+//     return 'id' in ref
+//   }
+
+//   export const isLogicalElement = (ref: DeploymentRef): ref is LogicalElement => {
+//     return 'element' in ref && !('id' in ref)
+//   }
+// }
+// export type DeploymentRef = ExclusiveUnion<{
+//   Node: DeploymentRef.Node
+//   Instance: DeploymentRef.Instance
+//   Element: DeploymentRef.LogicalElement
+// }>
+
+/**
+ * NOTE:
+ */
+export interface DeploymentRelation {
+  readonly id: RelationId
+  readonly source: DeploymentRef
+  readonly target: DeploymentRef
+  readonly title?: string
+  readonly tags?: NonEmptyArray<Tag> | null
+  readonly description?: string
+  readonly technology?: string
+  readonly kind?: RelationshipKind
+  readonly color?: Color
+  readonly line?: RelationshipLineType
+  readonly head?: RelationshipArrowType
+  readonly tail?: RelationshipArrowType
+  readonly links?: NonEmptyArray<Link> | null
+  // Link to dynamic view
+  readonly navigateTo?: ViewId
+  readonly metadata?: { [key: string]: string }
+}
+// export interface DeploymentRelation
+
+// interface Expressions {
+//   DeploymentRef: {
+//     ref: DeploymentRef
+//     isExpanded?: boolean
+//     isNested?: never
+//   } | {
+//     ref: DeploymentRef
+//     isExpanded?: never
+//     isNested?: boolean
+//   }
+
+//   Wildcard: {
+//     wildcard: true
+//   }
+// }
+
+type AllNever<Expressions> = UnionToIntersection<
+  {
+    [Name in keyof Expressions]: {
+      -readonly [Key in keyof Expressions[Name]]?: never
+    }
+  }[keyof Expressions]
+>
+
+type ExclusiveUnion<Expressions> = Expressions extends object ? {
+    [Name in keyof Expressions]: Simplify<Omit<AllNever<Expressions>, keyof Expressions[Name]> & Expressions[Name]>
+  }[keyof Expressions]
+  : Expressions
+
+export namespace DeploymentRelationExpression {
+  // type LogicalRefEndpoint = {
+  //   logicalRef: ElementRefExpr
+  // }
+  // export type DirectEndpoint = ExclusiveUnion<{
+  //   DeploymentElementExpression: DeploymentElementExpression
+  //   Logical: LogicalRefEndpoint
+  // }>
+
+  // export const isLogicalEndpoint = (expr: DirectEndpoint): expr is LogicalRefEndpoint => {
+  //   return 'logicalRef' in expr
+  // }
+
+  export type Direct = {
+    source: DeploymentElementExpression
+    target: DeploymentElementExpression
+    isBidirectional?: boolean
+  }
+  export const isDirect = (expr: DeploymentExpression): expr is Direct => {
+    return 'source' in expr && 'target' in expr
+  }
+  export type Incoming = {
+    incoming: DeploymentElementExpression
+  }
+  export const isIncoming = (expr: DeploymentExpression): expr is Incoming => {
+    return 'incoming' in expr
+  }
+  export type Outgoing = {
+    outgoing: DeploymentElementExpression
+  }
+  export const isOutgoing = (expr: DeploymentExpression): expr is Outgoing => {
+    return 'outgoing' in expr
+  }
+  export type InOut = {
+    inout: DeploymentElementExpression
+  }
+  export const isInOut = (expr: DeploymentExpression): expr is InOut => {
+    return 'inout' in expr
+  }
+}
+
+export type DeploymentRelationExpression = ExclusiveUnion<{
+  Direct: DeploymentRelationExpression.Direct
+  Incoming: DeploymentRelationExpression.Incoming
+  Outgoing: DeploymentRelationExpression.Outgoing
+  InOut: DeploymentRelationExpression.InOut
+}>
+
+export namespace DeploymentElementExpression {
+  export type Ref = {
+    ref: DeploymentRef
+    selector?:
+      | 'children' // ele.*
+      | 'expanded' // ele._
+      | 'descendants' // ele.**
+  }
+  export const isRef = (expr: DeploymentExpression): expr is Ref => {
+    return 'ref' in expr
+  }
+
+  export type Wildcard = {
+    wildcard: true
+  }
+  export const isWildcard = (expr: DeploymentExpression): expr is Wildcard => {
+    return 'wildcard' in expr && expr.wildcard === true
+  }
+}
+
+export type DeploymentElementExpression = ExclusiveUnion<{
+  DeploymentRef: DeploymentElementExpression.Ref
+  Wildcard: DeploymentElementExpression.Wildcard
+}>
+
+export type DeploymentExpression = ExclusiveUnion<{
+  Element: DeploymentElementExpression
+  Relation: DeploymentRelationExpression
+}>
+
+export namespace DeploymentExpression {
+  export type Element = DeploymentElementExpression
+  export type Relation = DeploymentRelationExpression
+
+  export const isElement = (expr: DeploymentExpression): expr is DeploymentElementExpression => {
+    return DeploymentElementExpression.isRef(expr) || DeploymentElementExpression.isWildcard(expr)
+  }
+  export const isRelation = (expr: DeploymentExpression): expr is DeploymentRelationExpression => {
+    return !DeploymentExpression.isElement(expr)
+  }
+}

package/src/types/element.ts

@@ -32,9 +32,13 @@ export const DefaultThemeColor = 'primary' satisfies ThemeColor
 export const DefaultElementShape = 'rectangle' satisfies ElementShape
 
 export interface ElementStyle {
-  border?: BorderStyle
-  // 0-100
-  opacity?: number
+  readonly border?: BorderStyle
+  /**
+   * In percentage 0-100, 0 is fully transparent
+   *
+   * @default 100
+   */
+  readonly opacity?: number
 }
 
 export type Tag<Tags extends string = string> = Tagged<Tags, 'Tag'>