@likec4/core 1.10.1 → 1.11.0

package/src/model/LikeC4ViewModel.ts

@@ -1,35 +1,37 @@
-import { isNullish, isString } from 'remeda'
+import { isNullish } from 'remeda'
 import { nonNullable } from '../errors'
-import type { ElementShape, Tag } from '../types/element'
-import type { Color } from '../types/theme'
+import {
+  type ElementKind as C4ElementKind,
+  type ElementShape as C4ElementShape,
+  type Tag as C4Tag
+} from '../types/element'
+import type { Color as C4Color } from '../types/theme'
 import type { ComputedEdge, ComputedNode, ComputedView } from '../types/view'
 import type { LikeC4Model } from './LikeC4Model'
-import type { EdgeId, Fqn } from './types'
-
-type ElementOrFqn = Fqn | LikeC4ViewModel.Element
+import { type EdgeId, type ElementOrFqn, type Fqn, getId, type IncomingFilter, type OutgoingFilter } from './types'
 
 /**
  * All methods are view-scoped, i.e. only return elements and connections in the view.
  */
 export class LikeC4ViewModel {
-  #rootElements = new Set<LikeC4ViewModel.Element>()
+  private _rootElements = new Set<LikeC4ViewModel.Element>()
 
-  #elements = new Map<Fqn, LikeC4ViewModel.Element>()
+  private _elements = new Map<Fqn, LikeC4ViewModel.Element>()
 
-  #connections: Map<EdgeId, LikeC4ViewModel.Connection>
+  private _connections: Map<EdgeId, LikeC4ViewModel.Connection>
 
   constructor(
     public readonly view: ComputedView,
-    public readonly model: LikeC4Model
+    public readonly model: LikeC4Model<LikeC4ViewModel>
   ) {
     for (const node of view.nodes) {
       const el = new LikeC4ViewModel.Element(node, this)
-      this.#elements.set(node.id, el)
+      this._elements.set(node.id, el)
       if (isNullish(node.parent)) {
-        this.#rootElements.add(el)
+        this._rootElements.add(el)
       }
     }
-    this.#connections = new Map(view.edges.map(e => [e.id, new LikeC4ViewModel.Connection(e, this)]))
+    this._connections = new Map(view.edges.map(e => [e.id, new LikeC4ViewModel.Connection(e, this)]))
   }
 
   get id() {
@@ -47,32 +49,32 @@ export class LikeC4ViewModel {
     return null
   }
 
-  get tags(): Tag[] {
+  get tags(): C4Tag[] {
     return this.view.tags ?? []
   }
 
   public roots(): ReadonlyArray<LikeC4ViewModel.Element> {
-    return [...this.#rootElements]
+    return [...this._rootElements]
   }
 
   public elements(): ReadonlyArray<LikeC4ViewModel.Element> {
-    return [...this.#elements.values()]
+    return [...this._elements.values()]
   }
 
   public element(id: Fqn): LikeC4ViewModel.Element {
-    return nonNullable(this.#elements.get(id), `LikeC4ViewModel.Element ${id} in view ${this.view.id} not found`)
+    return nonNullable(this._elements.get(id), `LikeC4ViewModel.Element ${id} in view ${this.id} not found`)
   }
 
   public hasElement(id: Fqn): boolean {
-    return this.#elements.has(id)
+    return this._elements.has(id)
   }
 
   public connections(): ReadonlyArray<LikeC4ViewModel.Connection> {
-    return [...this.#connections.values()]
+    return [...this._connections.values()]
   }
 
   public connection(id: EdgeId): LikeC4ViewModel.Connection {
-    return nonNullable(this.#connections.get(id), `Connection ${id} in view ${this.view.id}  not found`)
+    return nonNullable(this._connections.get(id), `Connection ${id} in view ${this.id}  not found`)
   }
 
   public findConnections(
@@ -80,8 +82,8 @@ export class LikeC4ViewModel {
     target: ElementOrFqn,
     direction: 'both' | 'direct' = 'direct'
   ): ReadonlyArray<LikeC4ViewModel.Connection> {
-    const sourceId = isString(source) ? source : source.id
-    const targetId = isString(target) ? target : target.id
+    const sourceId = getId(source)
+    const targetId = getId(target)
     return this.connections().filter(c =>
       (c.source.id === sourceId && c.target.id === targetId)
       || (direction === 'both' && c.source.id === targetId && c.target.id === sourceId)
@@ -89,18 +91,18 @@ export class LikeC4ViewModel {
   }
 
   public parent(element: ElementOrFqn): LikeC4ViewModel.Element | null {
-    const el = this.element(isString(element) ? element : element.id)
+    const el = this.element(getId(element))
     return el.node.parent ? this.element(el.node.parent) : null
   }
 
   public children(element: ElementOrFqn): ReadonlyArray<LikeC4ViewModel.Element> {
-    const el = this.element(isString(element) ? element : element.id)
+    const el = this.element(getId(element))
     return el.node.children.map(c => this.element(c))
   }
 
   // Get all sibling (i.e. same parent)
   public siblings(element: ElementOrFqn): ReadonlyArray<LikeC4ViewModel.Element> {
-    const id = isString(element) ? element : element.id
+    const id = getId(element)
     const parent = this.parent(id)
     const siblings = parent ? this.children(parent) : this.roots()
     return siblings.filter(e => e.id !== id)
@@ -111,7 +113,7 @@ export class LikeC4ViewModel {
    * (from closest to root)
    */
   public ancestors(element: ElementOrFqn): ReadonlyArray<LikeC4ViewModel.Element> {
-    let id = isString(element) ? element : element.id
+    let id = getId(element)
     const result = [] as LikeC4ViewModel.Element[]
     let parent
     while (parent = this.parent(id)) {
@@ -128,10 +130,10 @@ export class LikeC4ViewModel {
 
   public incoming(
     element: ElementOrFqn,
-    filter: 'all' | 'direct' | 'to-descendants' = 'all'
+    filter: IncomingFilter = 'all'
   ): ReadonlyArray<LikeC4ViewModel.Connection> {
-    const el = this.element(isString(element) ? element : element.id)
-    const edges = el.node.inEdges.map(e => nonNullable(this.#connections.get(e), `Edge ${e} not found`))
+    const el = this.element(getId(element))
+    const edges = el.node.inEdges.map(e => nonNullable(this._connections.get(e), `Edge ${e} not found`))
 
     if (filter === 'all' || edges.length === 0) {
       return edges
@@ -147,7 +149,7 @@ export class LikeC4ViewModel {
 
   public incomers(
     element: ElementOrFqn,
-    filter: 'all' | 'direct' | 'to-descendants' = 'all'
+    filter: IncomingFilter = 'all'
   ): ReadonlyArray<LikeC4ViewModel.Element> {
     return this.incoming(element, filter).map(r => r.source)
   }
@@ -157,10 +159,10 @@ export class LikeC4ViewModel {
    */
   public outgoing(
     element: ElementOrFqn,
-    filter: 'all' | 'direct' | 'from-descendants' = 'all'
+    filter: OutgoingFilter = 'all'
   ): ReadonlyArray<LikeC4ViewModel.Connection> {
-    const el = this.element(isString(element) ? element : element.id)
-    const edges = el.node.outEdges.map(e => nonNullable(this.#connections.get(e), `Edge ${e} not found`))
+    const el = this.element(getId(element))
+    const edges = el.node.outEdges.map(e => nonNullable(this._connections.get(e), `Edge ${e} not found`))
 
     if (filter === 'all' || edges.length === 0) {
       return edges
@@ -176,7 +178,7 @@ export class LikeC4ViewModel {
 
   public outgoers(
     element: ElementOrFqn,
-    filter: 'all' | 'direct' | 'from-descendants' = 'all'
+    filter: OutgoingFilter = 'all'
   ): ReadonlyArray<LikeC4ViewModel.Element> {
     return this.outgoing(element, filter).map(r => r.target)
   }
@@ -202,7 +204,7 @@ export namespace LikeC4ViewModel {
       return this.node.title
     }
 
-    get kind() {
+    get kind(): C4ElementKind {
       return this.node.kind
     }
 
@@ -214,19 +216,19 @@ export namespace LikeC4ViewModel {
       return this.node.children.length > 0
     }
 
-    get shape(): ElementShape {
+    get shape(): C4ElementShape {
       return this.node.shape
     }
 
-    get color(): Color {
+    get color(): C4Color {
       return this.node.color
     }
 
-    get tags(): Tag[] {
+    get tags(): C4Tag[] {
       return this.node.tags ?? []
     }
 
-    public model(): LikeC4Model.Element {
+    public model(): LikeC4Model.ElementModel<LikeC4ViewModel> {
       return this.viewmodel.model.element(this.id)
     }
 
@@ -268,11 +270,11 @@ export namespace LikeC4ViewModel {
       return this.viewmodel.incomers(this, filter)
     }
 
-    public outgoing(filter: 'all' | 'direct' | 'from-descendants' = 'all'): ReadonlyArray<LikeC4ViewModel.Connection> {
+    public outgoing(filter: OutgoingFilter = 'all'): ReadonlyArray<LikeC4ViewModel.Connection> {
       return this.viewmodel.outgoing(this, filter)
     }
 
-    public outgoers(filter: 'all' | 'direct' | 'from-descendants' = 'all'): ReadonlyArray<LikeC4ViewModel.Element> {
+    public outgoers(filter: OutgoingFilter = 'all'): ReadonlyArray<LikeC4ViewModel.Element> {
       return this.viewmodel.outgoers(this, filter)
     }
 
@@ -304,14 +306,14 @@ export namespace LikeC4ViewModel {
       return this.viewmodel.element(this.edge.target)
     }
 
-    get tags(): Tag[] {
+    get tags(): C4Tag[] {
       return this.edge.tags ?? []
     }
 
     /**
      * Model relationships
      */
-    relationships(): ReadonlyArray<LikeC4Model.Relationship> {
+    relationships(): ReadonlyArray<LikeC4Model.Relationship<LikeC4ViewModel>> {
       return this.edge.relations.map(r => nonNullable(this.viewmodel.model.relationship(r)))
     }
   }

package/src/model/index.ts

@@ -1,2 +1,3 @@
-export * from './LikeC4Model'
-export * from './LikeC4ViewModel'
+export { LikeC4DiagramModel } from './LikeC4DiagramModel'
+export { LikeC4Model } from './LikeC4Model'
+export { LikeC4ViewModel } from './LikeC4ViewModel'

package/src/model/types.ts

@@ -2,9 +2,22 @@ import type { Fqn as CoreFqn } from '../types/element'
 import type { RelationID as CoreRelationID } from '../types/relation'
 import type { EdgeId as CoreEdgeId, ViewID as CoreViewID } from '../types/view'
 
+import { isString } from 'remeda'
 import type { LiteralUnion } from 'type-fest'
 
 export type Fqn = LiteralUnion<CoreFqn, string>
 export type RelationID = LiteralUnion<CoreRelationID, string>
 export type ViewID = LiteralUnion<CoreViewID, string>
 export type EdgeId = LiteralUnion<CoreEdgeId, string>
+
+export type IncomingFilter = 'all' | 'direct' | 'to-descendants'
+export type OutgoingFilter = 'all' | 'direct' | 'from-descendants'
+
+export type ElementOrFqn = Fqn | { id: Fqn }
+
+/**
+ * Utility function to extract `id` from the given element.
+ */
+export function getId(element: ElementOrFqn): Fqn {
+  return isString(element) ? element : element.id
+}

package/src/types/index.ts

@@ -9,5 +9,3 @@ export * from './theme'
 export * from './view'
 export * from './view-changes'
 export * from './view-notation'
-
-export * as Expr from './expression'

package/src/types/model.ts

@@ -1,7 +1,7 @@
 import type { UnwrapTagged } from 'type-fest'
 import type { Element, ElementKind, ElementKindSpecification, Fqn, Tag } from './element'
 import type { Relation, RelationID, RelationshipKindSpecification } from './relation'
-import type { ComputedView, LikeC4View, ViewID } from './view'
+import type { ComputedView, DiagramView, LikeC4View, ViewID } from './view'
 
 /**
  * Parsed elements, relations, and views.
@@ -21,5 +21,14 @@ export interface ParsedLikeC4Model {
  * Same as `ParsedLikeC4Model` but with computed views.
  */
 export interface ComputedLikeC4Model extends Omit<ParsedLikeC4Model, 'views'> {
+  __?: never
   views: Record<ViewID, ComputedView>
 }
+
+/**
+ * Same as `ParsedLikeC4Model` but with layouted views (DiagramView)
+ */
+export interface LayoutedLikeC4Model extends Omit<ParsedLikeC4Model, 'views'> {
+  __: 'layouted'
+  views: Record<ViewID, DiagramView>
+}

package/src/utils/promises.ts

@@ -1,9 +1,20 @@
+import { randomInteger } from 'remeda'
+
 const DELAY = 'LIKEC4_DELAY'
 
-export function delay(ms: number = 100) {
+export function delay(): Promise<string>
+export function delay(ms: number): Promise<string>
+export function delay(randomFrom: number, randomTo: number): Promise<string>
+export function delay(...args: number[]): Promise<string> {
+  let ms = 100
+  if (args.length === 2) {
+    ms = randomInteger(args[0]!, args[1]!)
+  } else if (args.length === 1) {
+    ms = args[0]!
+  }
   return new Promise(resolve => {
     setTimeout(() => {
       resolve(DELAY)
-    }, ms)
+    }, ms ?? 100)
   })
 }

package/src/model/__test__/LikeC4Model.spec.ts

@@ -1,79 +0,0 @@
-import { prop } from 'remeda'
-import { describe, expect, it } from 'vitest'
-import { LikeC4Model } from '../LikeC4Model'
-import { fakeComputedModel, fakeElements } from './fixture'
-
-describe('LikeC4Model', () => {
-  const model = LikeC4Model.from(fakeComputedModel)
-
-  it('roots', () => {
-    expect(model.roots().map(prop('id'))).toEqual([
-      'customer',
-      'support',
-      'cloud',
-      'email',
-      'amazon'
-    ])
-  })
-
-  it('parent and chilren', () => {
-    const parent = model.parent('cloud.backend.graphql')!
-    expect(parent.id).toEqual('cloud.backend')
-    expect(parent.element).toStrictEqual(fakeElements['cloud.backend'])
-
-    const children = parent.children()
-
-    expect(children.map(prop('id'))).toEqual(['cloud.backend.graphql', 'cloud.backend.storage'])
-  })
-
-  it('ancestors in right order', () => {
-    const ancestors = model.element('cloud.frontend.dashboard').ancestors()
-    expect(ancestors).toHaveLength(2)
-    expect(ancestors[0]).toMatchObject({
-      id: 'cloud.frontend',
-      element: fakeElements['cloud.frontend']
-    })
-    expect(ancestors[1]).toMatchObject({
-      id: 'cloud',
-      element: fakeElements['cloud']
-    })
-  })
-
-  it('siblings of root', () => {
-    const siblings = model.element('cloud').siblings()
-    expect(siblings.map(prop('id'))).toEqual([
-      'customer',
-      'support',
-      'email',
-      'amazon'
-    ])
-  })
-
-  it('siblings', () => {
-    const backend = model.element('cloud.backend')
-
-    const siblings = backend.siblings()
-
-    expect(siblings.map(prop('id'))).toEqual(['cloud.frontend'])
-  })
-
-  it('descendants in right order', () => {
-    const descendants = model.element('cloud').descendants().map(prop('id'))
-    expect(descendants).toEqual([
-      'cloud.backend',
-      'cloud.backend.graphql',
-      'cloud.backend.storage',
-      'cloud.frontend',
-      'cloud.frontend.adminPanel',
-      'cloud.frontend.dashboard'
-    ])
-  })
-
-  it('internal relations', () => {
-    expect(
-      model.internal('cloud.backend').map(prop('id'))
-    ).toEqual([
-      'cloud.backend.graphql:cloud.backend.storage'
-    ])
-  })
-})

package/src/utils/compare-natural.spec.ts

@@ -1,37 +0,0 @@
-import { sort as remedaSort } from 'remeda'
-import { describe, expect, it } from 'vitest'
-import { compareNatural } from './compare-natural'
-
-describe('compareNatural', () => {
-  const sort = (array: Array<string | undefined>) => remedaSort(array, compareNatural)
-
-  it('should move undefined to the end', () => {
-    expect(
-      sort([
-        undefined,
-        'apple',
-        undefined,
-        'banana'
-      ])
-    ).toEqual([
-      'apple',
-      'banana',
-      undefined,
-      undefined
-    ])
-  })
-
-  it('should sort array of strings', () => {
-    expect(sort([
-      'apple1',
-      'apple11',
-      'apple2',
-      'apple10'
-    ])).toEqual([
-      'apple1',
-      'apple2',
-      'apple10',
-      'apple11'
-    ])
-  })
-})

package/src/utils/fqn.spec.ts

@@ -1,202 +0,0 @@
-import { prop } from 'remeda'
-import { describe, expect, it } from 'vitest'
-import type { Element, Fqn } from '../types'
-import {
-  ancestorsFqn,
-  commonAncestor,
-  compareFqnHierarchically,
-  isAncestor,
-  isDescendantOf,
-  notDescendantOf,
-  parentFqn,
-  sortByFqnHierarchically,
-  sortNaturalByFqn
-} from './fqn'
-
-const el = (id: string): Element => ({ id }) as unknown as Element
-
-describe('parentFqn', () => {
-  it('should return null if no parent', () => {
-    expect(parentFqn('a' as Fqn)).toBeNull()
-  })
-  it('should return parent', () => {
-    expect(parentFqn('a.b' as Fqn)).toBe('a')
-    expect(parentFqn('a.b.c' as Fqn)).toBe('a.b')
-  })
-})
-
-describe('ancestorsFqn', () => {
-  it('should return empty array if no parent', () => {
-    expect(ancestorsFqn('a' as Fqn)).toEqual([])
-  })
-  it('should return ancestors', () => {
-    expect(ancestorsFqn('a.b.c.d.e' as Fqn)).toEqual(['a.b.c.d', 'a.b.c', 'a.b', 'a'])
-  })
-})
-
-describe('commonAncestor', () => {
-  it('should return null if no common ancestor', () => {
-    expect(commonAncestor('a' as Fqn, 'b' as Fqn)).toBeNull()
-    expect(commonAncestor('a.b' as Fqn, 'c.d' as Fqn)).toBeNull()
-  })
-
-  it('should return common ancestor', () => {
-    expect(commonAncestor('a.b' as Fqn, 'a.c' as Fqn)).toBe('a')
-    expect(commonAncestor('a.b.c' as Fqn, 'a.b.e' as Fqn)).toBe('a.b')
-    expect(commonAncestor('a.b.c.d.e' as Fqn, 'a.b.c.d' as Fqn)).toBe('a.b.c')
-  })
-})
-
-describe('isAncestor', () => {
-  it('should return true if ancestor', () => {
-    expect(isAncestor('a' as Fqn, 'a.b' as Fqn)).toBe(true)
-    expect(isAncestor('a.b' as Fqn, 'a.b.c' as Fqn)).toBe(true)
-  })
-  it('should return false if not ancestor', () => {
-    expect(isAncestor('a' as Fqn, 'b' as Fqn)).toBe(false)
-    expect(isAncestor('a.b' as Fqn, 'a' as Fqn)).toBe(false)
-    expect(isAncestor('a.b' as Fqn, 'b.a' as Fqn)).toBe(false)
-  })
-})
-
-describe('isDescendantOf', () => {
-  const predicate = isDescendantOf(['a', 'b', 'a.b', 'a.b.c'].map(el))
-
-  it('should return true if isDescendantOf', () => {
-    expect(predicate(el('a'))).toBe(true)
-    expect(predicate(el('b.c'))).toBe(true)
-    expect(predicate(el('a.b.c.d.e'))).toBe(true)
-  })
-  it('should return false if not descendantOf', () => {
-    expect(predicate(el('c'))).toBe(false)
-    expect(predicate(el('ac'))).toBe(false)
-    expect(predicate(el('d.a.c'))).toBe(false)
-  })
-})
-
-describe('notDescendantOf', () => {
-  const predicate = notDescendantOf(['a', 'b', 'a.b', 'a.b.c'].map(el))
-
-  it('should return true if notDescendantOf', () => {
-    expect(predicate(el('c'))).toBe(true)
-    expect(predicate(el('ac'))).toBe(true)
-    expect(predicate(el('d.a.c'))).toBe(true)
-  })
-  it('should return false if descendantOf', () => {
-    expect(predicate(el('a'))).toBe(false)
-    expect(predicate(el('b.c'))).toBe(false)
-    expect(predicate(el('a.b.c.d.e'))).toBe(false)
-  })
-})
-
-describe('compareFqnHierarchically', () => {
-  it('should compare hierarchically', () => {
-    expect([
-      'a',
-      'b',
-      'a.b',
-      'a.b.c',
-      'a.c.c'
-    ].sort(compareFqnHierarchically)).toEqual([
-      'a',
-      'b',
-      'a.b',
-      'a.b.c',
-      'a.c.c'
-    ])
-  })
-
-  it('should preserve initial order', () => {
-    expect(
-      ['aaa', 'aa', 'a', 'aaa.c', 'aa.b', 'a.c', 'a.b'].sort(compareFqnHierarchically)
-    ).toEqual(['aaa', 'aa', 'a', 'aaa.c', 'aa.b', 'a.c', 'a.b'])
-  })
-})
-
-describe('sortNaturalByFqn', () => {
-  it('should sort hierarchically', () => {
-    expect(
-      sortNaturalByFqn([
-        el('a.b'),
-        el('a'),
-        el('a.c.a.b'),
-        el('a.c.c'),
-        el('b'),
-        el('a.b.c')
-      ]).map(prop('id'))
-    ).toEqual([
-      'a',
-      'b',
-      'a.b',
-      'a.b.c',
-      'a.c.c',
-      'a.c.a.b'
-    ])
-  })
-
-  it('should sort natural', () => {
-    expect(
-      sortNaturalByFqn([
-        el('b'),
-        el('a.c.c'),
-        el('a'),
-        el('a.b1'),
-        el('a.b2'),
-        el('a.b10'),
-        el('a.b2.c')
-      ]).map(prop('id'))
-    ).toEqual([
-      'a',
-      'b',
-      'a.b1',
-      'a.b2',
-      'a.b10',
-      'a.b2.c',
-      'a.c.c'
-    ])
-  })
-})
-
-describe('sortByFqnHierarchically', () => {
-  it('should sort hierarchically', () => {
-    expect(
-      sortByFqnHierarchically([
-        el('a.b'),
-        el('a'),
-        el('a.b.c'),
-        el('a.c.a.b'),
-        el('a.c.c'),
-        el('b')
-      ]).map(prop('id'))
-    ).toEqual([
-      'a',
-      'b',
-      'a.b',
-      'a.b.c',
-      'a.c.c',
-      'a.c.a.b'
-    ])
-  })
-
-  it('should preserve initial order', () => {
-    expect(
-      sortByFqnHierarchically([
-        el('b'),
-        el('a.c.c'),
-        el('a'),
-        el('a.b10'),
-        el('a.b2.c'),
-        el('a.b1'),
-        el('a.b2')
-      ]).map(prop('id'))
-    ).toEqual([
-      'b',
-      'a',
-      'a.b10',
-      'a.b1',
-      'a.b2',
-      'a.c.c',
-      'a.b2.c'
-    ])
-  })
-})