@likec4/core 1.17.1 → 1.18.0

package/src/model/RelationModel.ts

@@ -0,0 +1,84 @@
+import { isEmpty } from 'remeda'
+import type { Link, Tag } from '../types/element'
+import type { Relation } from '../types/relation'
+import { commonAncestor } from '../utils/fqn'
+import type { ElementModel } from './ElementModel'
+import type { LikeC4Model } from './LikeC4Model'
+import type { AnyAux, IteratorLike } from './types'
+import type { LikeC4ViewModel, ViewsIterator } from './view/LikeC4ViewModel'
+
+export type RelationshipsIterator<M extends AnyAux> = IteratorLike<RelationshipModel<M>>
+
+export class RelationshipModel<M extends AnyAux> {
+  public readonly source: ElementModel<M>
+  public readonly target: ElementModel<M>
+
+  /**
+   * Common ancestor of the source and target elements.
+   * Represents the boundary of the Relation.
+   */
+  public readonly boundary: ElementModel<M> | null
+
+  constructor(
+    public readonly model: LikeC4Model<M>,
+    public readonly $relationship: Relation
+  ) {
+    this.source = model.element($relationship.source)
+    this.target = model.element($relationship.target)
+    const parent = commonAncestor(this.source.id, this.target.id)
+    this.boundary = parent ? this.model.element(parent) : null
+  }
+
+  get id(): M['RelationId'] {
+    return this.$relationship.id
+  }
+
+  get expression(): string {
+    return `${this.source.id} -> ${this.target.id}`
+  }
+
+  get title(): string | null {
+    if (isEmpty(this.$relationship.title)) {
+      return null
+    }
+    return this.$relationship.title
+  }
+
+  get technology(): string | null {
+    if (isEmpty(this.$relationship.technology)) {
+      return null
+    }
+    return this.$relationship.technology
+  }
+
+  get description(): string | null {
+    if (isEmpty(this.$relationship.description)) {
+      return null
+    }
+    return this.$relationship.description
+  }
+
+  get navigateTo(): LikeC4ViewModel<M> | null {
+    return this.$relationship.navigateTo ? this.model.view(this.$relationship.navigateTo) : null
+  }
+
+  get tags(): ReadonlyArray<Tag> {
+    return this.$relationship.tags ?? []
+  }
+
+  get links(): ReadonlyArray<Link> {
+    return this.$relationship.links ?? []
+  }
+
+  /**
+   * Iterate over all views that include this relationship.
+   */
+  public *views(): ViewsIterator<M> {
+    for (const view of this.model.views()) {
+      if (view.includesRelation(this.id)) {
+        yield view
+      }
+    }
+    return
+  }
+}

package/src/model/__test__/fixture.ts

@@ -1,343 +1,158 @@
-import { mapToObj } from 'remeda'
-import type { LiteralUnion, Tagged, UnwrapTagged } from 'type-fest'
-import {
-  type ComputedLikeC4Model,
-  type Element,
-  type ElementKindSpecification,
-  type NonEmptyArray,
-  type Relation,
-  type RelationshipArrowType,
-  type RelationshipLineType,
-  type Tag,
-  type ThemeColor
-} from '../../types'
-
-/**
-              ┌──────────────────────────────────────────────────┐
-              │                      cloud                       │
-              │  ┌───────────────────────────────────────────┐   │
-              │  │                 frontend                  │   │
-┏━━━━━━━━━━┓  │  │   ┏━━━━━━━━━━━━━┓   ┏━━━━━━━━━━━━━━━━┓    │   │   ┏━━━━━━━━━━━┓
-┃          ┃  │  │   ┃             ┃   ┃                ┃    │   │   ┃           ┃
-┃ customer ┃──┼──┼──▶┃  dashboard  ┃   ┃   adminpanel   ┃◀───┼───┼───┃  support  ┃
-┃          ┃  │  │   ┃             ┃   ┃                ┃    │   │   ┃           ┃
-┗━━━━━━━━━━┛  │  │   ┗━━━━━━┳━━━━━━┛   ┗━━━━━━━━┳━━━━━━━┛    │   │   ┗━━━━━━━━━━━┛
-              │  └──────────┼───────────────────┼────────────┘   │
-              │             ├───────────────────┘                │
-              │             │                                    │
-              │  ┌──────────┼────────────────────────────────┐   │
-              │  │          ▼       backend                  │   │
-              │  │   ┏━━━━━━━━━━━━━┓       ┏━━━━━━━━━━━━━┓   │   │
-              │  │   ┃             ┃       ┃             ┃   │   │
-              │  │   ┃  graphlql   ┃──────▶┃   storage   ┃   │   │
-              │  │   ┃             ┃       ┃             ┃   │   │
-              │  │   ┗━━━━━━━━━━━━━┛       ┗━━━━━━┳━━━━━━┛   │   │
-              │  └────────────────────────────────┼──────────┘   │
-              └───────────────────────────────────┼──────────────┘
-                                                  │
-                                        ┌─────────┼─────────┐
-                                        │ amazon  │         │
-                                        │         ▼         │
-                                        │ ┏━━━━━━━━━━━━━━┓  │
-                                        │ ┃              ┃  │
-                                        │ ┃      s3      ┃  │
-                                        │ ┃              ┃  │
-                                        │ ┗━━━━━━━━━━━━━━┛  │
-                                        └───────────────────┘
-
-specification {
-  element actor
-  element system
-  element container
-  element component
-
-  tag old
-}
-
-model {
-
-  actor customer
-  actor support
-
-  system cloud {
-    container backend {
-      component graphql
-      component storage {
-        #old
-      }
-
-      graphql -> storage
-    }
-
-    container frontend {
-      component dashboard {
-        -> graphql
+import { Builder } from '../../builder/Builder'
+import { computeViews } from '../../compute-view/compute-view'
+import { LikeC4Model } from '../LikeC4Model'
+
+const {
+  builder: b,
+  model: {
+    person,
+    system,
+    component,
+    webapp,
+    mobile,
+    ...$m
+  },
+  deployment: {
+    deployment,
+    env,
+    node,
+    zone,
+    instanceOf,
+    ...$d
+  },
+  views: {
+    view,
+    views,
+    viewOf,
+    deploymentView,
+    $rules,
+    $include,
+    $exclude,
+    $style
+  }
+} = Builder.forSpecification({
+  elements: {
+    person: {
+      style: {
+        shape: 'person'
       }
-      component adminPanel {
-        #old
-        -> graphql
+    },
+    system: {},
+    component: {},
+    webapp: {
+      style: {
+        shape: 'browser'
       }
-    }
-  }
-
-  customer -> dashboard
-  support -> adminPanel
-
-  system amazon {
-    component s3
-
-    cloud.backend.storage -> s3
-  }
-
-}
-
- */
-type TestTag = 'old' | 'next' | 'aws' | 'storage' | 'communication' | 'legacy'
-
-const el = <Id extends string, Kind extends string>({
-  id,
-  kind,
-  title,
-  style,
-  tags,
-  ...props
-}: Partial<Omit<Element, 'id' | 'kind' | 'tags'>> & {
-  id: Id
-  kind: Kind
-  tags?: NonEmptyArray<TestTag>
-}) =>
-  ({
-    id: id as Tagged<Id, 'Fqn'>,
-    kind: kind as Tagged<Kind, 'ElementKind'>,
-    title: title ?? id,
-    description: null,
-    technology: null,
-    tags: tags as NonEmptyArray<Tag> ?? null,
-    links: null,
-    style: {
-      ...style
     },
-    ...props
-  }) satisfies Element
-
-const fakeElementsArr = [
-  el({
-    id: 'customer',
-    kind: 'actor',
-    title: 'customer',
-    shape: 'person'
-  }),
-  el({
-    id: 'support',
-    kind: 'actor',
-    title: 'support',
-    shape: 'person'
-  }),
-  el({
-    id: 'cloud',
-    kind: 'system',
-    title: 'cloud',
-    tags: ['next', 'old']
-  }),
-  el({
-    id: 'cloud.backend',
-    kind: 'container',
-    title: 'backend'
-  }),
-  el({
-    id: 'cloud.frontend',
-    kind: 'container',
-    title: 'frontend',
-    shape: 'browser'
-  }),
-  el({
-    id: 'cloud.backend.graphql',
-    kind: 'component',
-    title: 'graphql'
-  }),
-  el({
-    id: 'email',
-    kind: 'system',
-    title: 'email'
-  }),
-  el({
-    id: 'cloud.backend.storage',
-    kind: 'component',
-    title: 'storage',
-    tags: ['storage', 'old']
-  }),
-  el({
-    id: 'cloud.frontend.adminPanel',
-    kind: 'component',
-    title: 'adminPanel',
-    tags: ['old']
-  }),
-  el({
-    id: 'cloud.frontend.dashboard',
-    kind: 'component',
-    title: 'dashboard',
-    tags: ['next']
-  }),
-  el({
-    id: 'amazon',
-    kind: 'system',
-    title: 'amazon',
-    tags: ['aws']
-  }),
-  el({
-    id: 'amazon.s3',
-    kind: 'component',
-    title: 's3',
-    shape: 'storage',
-    tags: ['aws', 'storage']
-  })
-] as const
-
-export type FakeElementIds = UnwrapTagged<(typeof fakeElementsArr)[number]['id']>
-export type FakeElementKinds = UnwrapTagged<(typeof fakeElementsArr)[number]['kind']>
-
-export const fakeElements = mapToObj(fakeElementsArr, e => [e.id as FakeElementIds, e])
-
-const rel = <Source extends FakeElementIds, Target extends FakeElementIds, Kind extends string>({
-  source,
-  target,
-  title,
-  kind,
-  tags,
-  ...props
-}: {
-  source: LiteralUnion<Source, string>
-  target: LiteralUnion<Target, string>
-  title?: string
-  kind?: LiteralUnion<Kind, string>
-  color?: ThemeColor
-  line?: RelationshipLineType
-  head?: RelationshipArrowType
-  tail?: RelationshipArrowType
-  tags?: NonEmptyArray<TestTag>
-}) =>
-  ({
-    id: `${source}:${target}` as Tagged<`${Source}:${Target}`, 'RelationID'>,
-    title: title ?? '',
-    source: source as Tagged<Source, 'Fqn'>,
-    target: target as Tagged<Target, 'Fqn'>,
-    ...(kind ? { kind: kind as Tagged<Kind, 'RelationshipKind'> } : {}),
-    tags: tags as NonEmptyArray<Tag> ?? null,
-    ...props
-  }) satisfies Relation
-
-const fakeRelationsArr = [
-  rel({
-    source: 'customer',
-    target: 'cloud.frontend.dashboard',
-    title: 'opens in browser'
-  }),
-  rel({
-    source: 'support',
-    target: 'cloud.frontend.adminPanel',
-    title: 'manages'
-  }),
-  rel({
-    source: 'cloud.backend.storage',
-    target: 'amazon.s3',
-    title: 'uploads',
-    tags: ['aws', 'storage', 'legacy']
-  }),
-  rel({
-    source: 'customer',
-    target: 'cloud',
-    title: 'uses'
-  }),
-  rel({
-    source: 'customer',
-    target: 'cloud.frontend',
-    title: 'uses frontend'
-  }),
-  rel({
-    source: 'cloud.backend.graphql',
-    target: 'cloud.backend.storage',
-    title: 'stores',
-    tags: ['old', 'storage']
-  }),
-  rel({
-    source: 'cloud.frontend',
-    target: 'cloud.backend',
-    title: 'requests'
-  }),
-  rel({
-    source: 'cloud.frontend.dashboard',
-    target: 'cloud.backend.graphql',
-    kind: 'graphlql',
-    title: 'requests',
-    line: 'solid',
-    tags: ['next']
-  }),
-  rel({
-    source: 'cloud.frontend.adminPanel',
-    target: 'cloud.backend.graphql',
-    kind: 'graphlql',
-    title: 'fetches',
-    line: 'dashed',
-    tail: 'odiamond',
-    tags: ['old']
-  }),
-  rel({
-    source: 'cloud',
-    target: 'amazon',
-    title: 'uses',
-    head: 'diamond',
-    tail: 'odiamond',
-    tags: ['aws']
-  }),
-  rel({
-    source: 'cloud.backend',
-    target: 'email',
-    title: 'schedule',
-    tags: ['communication']
-  }),
-  rel({
-    source: 'cloud',
-    target: 'email',
-    title: 'uses',
-    tags: ['communication']
-  }),
-  rel({
-    source: 'email',
-    target: 'cloud',
-    title: 'notifies',
-    tags: ['communication']
-  })
-] as const
-
-export type FakeRelationIds = UnwrapTagged<(typeof fakeRelationsArr)[number]['id']>
-
-export const fakeRelations = mapToObj(fakeRelationsArr, r => [r.id as FakeRelationIds, r])
-
-export const fakeComputedModel = {
-  specification: {
-    tags: [],
-    relationships: {},
-    elements: {
-      actor: {
-        style: {}
-      },
-      system: {
-        style: {}
-      },
-      container: {
-        style: {}
-      },
-      component: {
-        style: {}
+    mobile: {
+      style: {
+        shape: 'mobile'
       }
-    } satisfies Record<FakeElementKinds, ElementKindSpecification>
-  },
-  elements: fakeElements,
-  relations: fakeRelations,
-  globals: {
-    predicates: {},
-    dynamicPredicates: {},
-    styles: {}
+    }
   },
-  views: {}
-} satisfies ComputedLikeC4Model
+  deployments: {
+    env: {},
+    zone: {},
+    node: {}
+  }
+})
+
+const local = b
+  .with(
+    $m.model(
+      person('customer'),
+      system('cloud').with(
+        component('frontend').with(
+          webapp('dashboard'),
+          mobile('mobile')
+        ),
+        component('auth'),
+        component('backend').with(
+          component('api'),
+          component('graphql')
+        ),
+        component('media', {
+          shape: 'storage'
+        })
+      ),
+      system('aws').with(
+        component('rds', {
+          shape: 'storage'
+        }),
+        component('s3', {
+          shape: 'storage'
+        })
+      ),
+      system('email')
+    ),
+    $m.model(
+      $m.rel('customer', 'cloud', 'uses services'),
+      $m.rel('customer', 'cloud.frontend.mobile', 'opens mobile app'),
+      $m.rel('customer', 'cloud.frontend.dashboard', 'opens in browser'),
+      $m.rel('cloud.frontend.dashboard', 'cloud.auth', 'authenticates'),
+      $m.rel('cloud.frontend.dashboard', 'cloud.backend.api', 'fetches data'),
+      $m.rel('cloud.frontend.dashboard', 'cloud.media', 'fetches media'),
+      $m.rel('cloud.frontend.mobile', 'cloud.auth', 'authenticates'),
+      $m.rel('cloud.frontend.mobile', 'cloud.backend.api', 'fetches data'),
+      $m.rel('cloud.frontend.mobile', 'cloud.media', 'fetches media'),
+      $m.rel('cloud.frontend', 'cloud.backend')
+    ),
+    $m.model(
+      $m.rel('cloud.backend.api', 'cloud.auth', 'authorizes'),
+      $m.rel('cloud.backend.api', 'cloud.media', 'uploads media'),
+      $m.rel('cloud.backend.api', 'aws.rds', 'reads/writes'),
+      $m.rel('cloud.backend.api', 'email', 'sends emails'),
+      $m.rel('cloud.media', 'aws.s3', 'uploads'),
+      $m.rel('email', 'customer', 'sends emails')
+    ),
+    deployment(
+      node('customer').with(
+        instanceOf('instance', 'customer')
+      ),
+      env('prod').with(
+        zone('eu').with(
+          zone('zone1').with(
+            instanceOf('ui', 'cloud.frontend.dashboard'),
+            instanceOf('api', 'cloud.backend.api')
+          ),
+          zone('zone2').with(
+            instanceOf('ui', 'cloud.frontend.dashboard'),
+            instanceOf('api', 'cloud.backend.api')
+          ),
+          instanceOf('media', 'cloud.media'),
+          instanceOf('db', 'aws.rds')
+        ),
+        zone('us').with(
+          instanceOf('db', 'aws.rds')
+        )
+      ),
+      $d.rel('prod.eu.db', 'prod.us.db', 'replicates')
+    ),
+    views(
+      view('index', $include('*')),
+      viewOf(
+        'cloud',
+        'cloud',
+        $rules(
+          $include('*'),
+          $include('cloud.frontend.dashboard')
+        )
+      ),
+      deploymentView(
+        'prod',
+        $rules(
+          $include('customer.instance'),
+          $include('prod.eu.zone1.ui')
+        )
+      )
+    )
+  )
+
+export const builder = local.clone()
+
+export const parsed = local.build()
+export type TestFqn = typeof local.Types.Fqn
+
+export const computed = computeViews(parsed)
+
+export const model = LikeC4Model.create(computed)

package/src/model/connection/ConnectionModel.ts

@@ -0,0 +1,94 @@
+import { invariant } from '../../errors'
+import { difference, equals, 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'
+
+export interface Connection<Elem = any, Id = any> {
+  readonly id: Id
+  readonly source: Elem
+  readonly target: Elem
+
+  /**
+   * Common ancestor of the source and target elements.
+   * Represents the boundary of the connection.
+   */
+  readonly boundary: Elem | null
+
+  /**
+   * Human readable expression of the connection
+   * Mostly used for testing and debugging
+   */
+  readonly expression: string
+
+  mergeWith(this: Connection<any, any>, other: typeof this): typeof this
+
+  nonEmpty(): boolean
+
+  difference(this: Connection<Elem, Id>, other: Connection<Elem, Id>): typeof this
+}
+
+/**
+ * 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']
+
+  /**
+   * Common ancestor of the source and target elements.
+   * Represents the boundary of the connection.
+   */
+  public readonly boundary: ElementModel<M> | null
+
+  constructor(
+    public readonly source: ElementModel<M>,
+    public readonly target: ElementModel<M>,
+    public readonly relations: ReadonlySet<RelationshipModel<M>>
+  ) {
+    this.id = stringHash(`model:${source.id}:${target.id}`) as M['EdgeId']
+    this.boundary = source.commonAncestor(target)
+  }
+
+  /**
+   * Human readable expression of the connection
+   * Mostly used for testing and debugging
+   */
+  get expression(): string {
+    return `${this.source.id} -> ${this.target.id}`
+  }
+
+  nonEmpty(): boolean {
+    return this.relations.size > 0
+  }
+
+  mergeWith(other: ConnectionModel<M>): 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>): ConnectionModel<M> {
+    invariant(this.source.id === other.source.id, 'Cannot difference connection with different sources')
+    invariant(this.target.id === other.target.id, 'Cannot difference connection with different targets')
+    return new ConnectionModel(
+      this.source,
+      this.target,
+      difference(this.relations, other.relations)
+    )
+  }
+
+  equals(other: ConnectionModel<M>): boolean {
+    return this.id === other.id
+      && this.source.id === other.source.id
+      && this.target.id === other.target.id
+      && equals(this.relations, other.relations)
+  }
+}