@likec4/core 1.17.1 → 1.19.0

package/src/model/view/LikeC4ViewModel.ts

@@ -0,0 +1,226 @@
+import { sort } from 'remeda'
+import { nonNullable } from '../../errors'
+import type { IteratorLike } from '../../types'
+import type { Link, Tag } from '../../types/element'
+import {
+  type ComputedDeploymentView,
+  type ComputedDynamicView,
+  type ComputedElementView,
+  type ComputedView,
+  type DiagramView,
+  type EdgeId as C4EdgeId,
+  type LikeC4View,
+  type NodeId as C4NodeId,
+  isDeploymentView,
+  isDynamicView,
+  isElementView,
+  isScopedElementView,
+} from '../../types/view'
+import { compareByFqnHierarchically, getOrCreate } from '../../utils'
+import type { ElementModel } from '../ElementModel'
+import type { LikeC4Model } from '../LikeC4Model'
+import { type AnyAux, getId } from '../types'
+import { type EdgesIterator, EdgeModel } from './EdgeModel'
+import { type NodesIterator, NodeModel } 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, Object.freeze(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,
+        Object.freeze(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,229 @@
+import {
+  type Color as C4Color,
+  type ComputedView,
+  type DeploymentNodeKind,
+  type DiagramView,
+  type ElementShape as C4ElementShape,
+  type IteratorLike,
+  type Link,
+  type NodeId,
+  type Tag as C4Tag,
+  ComputedNode,
+  ElementKind,
+} from '../../types'
+import type { DeployedInstanceModel, DeploymentElementModel } from '../DeploymentElementModel'
+import type { ElementModel } from '../ElementModel'
+import type { AnyAux, IncomingFilter, 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

@@ -1,4 +1,4 @@
-import type { Tagged } from 'type-fest'
+import type { Simplify, Tagged, UnionToIntersection } from 'type-fest'
 
 export type NonEmptyArray<T> = [T, ...T[]]
 
@@ -14,3 +14,57 @@ export interface XYPoint {
   x: number
   y: number
 }
+
+export type KeysOf<T> = keyof T extends infer K extends string ? K : never
+
+type AllNever<Expressions> = UnionToIntersection<
+  {
+    [Name in keyof Expressions]: {
+      -readonly [Key in keyof Expressions[Name]]?: never
+    }
+  }[keyof Expressions]
+>
+
+/**
+ * @example
+ *   type Variant1 = {
+ *     a: string
+ *   }
+ *   type Variant2 = {
+ *     b: number
+ *   }
+ *
+ *   type Variants = ExclusiveUnion<{
+ *     Variant1: Variant1,
+ *     Variant2: Variant2
+ *   }>
+ *
+ *   Fail here
+ *   const variant1: Variants = {
+ *      a: 'one',
+ *      b: 1
+ *   }
+ */
+
+export type ExclusiveUnion<Expressions> = Expressions extends object ? {
+    [Name in keyof Expressions]: Simplify<Omit<AllNever<Expressions>, keyof Expressions[Name]> & Expressions[Name]>
+  }[keyof Expressions]
+  : Expressions
+
+/**
+ * Copy from https://github.com/remeda/remeda/blob/main/src/internal/types/NTuple.ts
+ * An array with *exactly* N elements in it.
+ *
+ * Only literal N values are supported. For very large N the type might result
+ * in a recurse depth error. For negative N the type would result in an infinite
+ * recursion. None of these have protections because this is an internal type!
+ */
+export type NTuple<
+  T,
+  N extends number,
+  Result extends Array<unknown> = [],
+> = Result['length'] extends N ? Result : NTuple<T, N, [...Result, T]>
+
+export type IteratorLike<T> = IteratorObject<T, BuiltinIteratorReturn>
+
+export type Predicate<T> = (x: T) => boolean

package/src/types/deployments.ts

@@ -0,0 +1,169 @@
+import type { MergeExclusive, Simplify, Tagged } from 'type-fest'
+import type { IconUrl, NonEmptyArray } from './_common'
+import type { ElementShape, ElementStyle, Fqn, Link, Tag } from './element'
+import type { AbstractRelation, RelationId } from './relation'
+import type { Color } from './theme'
+
+export type DeploymentNodeKind<Kinds extends string = string> = Tagged<Kinds, 'DeploymentNodeKind'>
+
+export type DeploymentElementStyle = ElementStyle & {
+  readonly icon?: IconUrl
+  readonly shape?: ElementShape
+  readonly color?: Color
+}
+
+export interface DeploymentNodeKindSpecification {
+  readonly technology?: string
+  readonly notation?: string
+  readonly style: DeploymentElementStyle
+}
+
+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?: DeploymentElementStyle
+  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?: DeploymentElementStyle
+  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 type PredicateSelector =
+  | 'children' // ele.*
+  | 'expanded' // ele._
+  | 'descendants' // ele.**
+
+export interface DeploymentRef {
+  // Reference to DeploymentNode or DeployedInstance
+  readonly id: Fqn
+  // Reference to element within DeployedInstance
+  readonly element?: Fqn
+}
+
+/**
+ * NOTE:
+ */
+export interface DeploymentRelation extends AbstractRelation {
+  readonly id: RelationId
+  readonly source: DeploymentRef
+  readonly target: DeploymentRef
+}
+
+// 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: FqnExpression.Element
+//     target: FqnExpression.Element
+//     isBidirectional?: boolean
+//   }
+//   export const isDirect = (expr: DeploymentExpression): expr is Direct => {
+//     return 'source' in expr && 'target' in expr
+//   }
+//   export type Incoming = {
+//     incoming: FqnExpression.Element
+//   }
+//   export const isIncoming = (expr: DeploymentExpression): expr is Incoming => {
+//     return 'incoming' in expr
+//   }
+//   export type Outgoing = {
+//     outgoing: FqnExpression.Element
+//   }
+//   export const isOutgoing = (expr: DeploymentExpression): expr is Outgoing => {
+//     return 'outgoing' in expr
+//   }
+//   export type InOut = {
+//     inout: FqnExpression.Element
+//   }
+//   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?: PredicateSelector
+//   }
+//   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

@@ -28,13 +28,17 @@ export const ElementShapes = [
 ] as const
 
 export type ElementShape = TupleToUnion<typeof ElementShapes>
-export const DefaultThemeColor = 'primary' satisfies ThemeColor
-export const DefaultElementShape = 'rectangle' satisfies ElementShape
+export const DefaultThemeColor: ThemeColor = 'primary'
+export const DefaultElementShape: ElementShape = 'rectangle'
 
 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'>