@likec4/core 1.12.2 → 1.13.0

package/src/builder/_types.ts

@@ -0,0 +1,195 @@
+import type { IfNever, IsLiteral, Tagged, TupleToUnion } from 'type-fest'
+import type {
+  BorderStyle,
+  Color,
+  ElementKindSpecification,
+  ElementShape,
+  ParsedLikeC4Model,
+  RelationshipArrowType,
+  RelationshipKindSpecification,
+  RelationshipLineType
+} from '../types'
+
+type KeysOf<T> = keyof T extends infer K extends string ? K : never
+
+export type BuilderSpecification = {
+  elements: {
+    [kind: string]: Partial<ElementKindSpecification>
+  }
+  relationships?: Record<string, Partial<RelationshipKindSpecification>>
+  tags?: [string, ...string[]]
+  metadataKeys?: [string, ...string[]]
+}
+
+type Metadata<MetadataKey extends string> = IfNever<MetadataKey, never, Record<MetadataKey, string>>
+
+export type NewElementProps<Tag, Metadata> = {
+  title?: string
+  description?: string
+  technology?: string
+  tags?: IfNever<Tag, never, [Tag, ...Tag[]]>
+  metadata?: Metadata
+  icon?: string
+  shape?: ElementShape
+  color?: Color
+  links?: Array<string | { title?: string; url: string }>
+  style?: {
+    border?: BorderStyle
+    // 0-100
+    opacity?: number
+  }
+}
+
+export type NewViewProps<Tag> = {
+  title?: string
+  description?: string
+  tags?: IfNever<Tag, never, [Tag, ...Tag[]]>
+  links?: Array<string | { title?: string; url: string }>
+}
+
+export type NewRelationProps<Kind, Tag, Metadata> = {
+  kind?: Kind
+  title?: string
+  description?: string
+  technology?: string
+  tags?: IfNever<Tag, never, [Tag, ...Tag[]]>
+  metadata?: Metadata
+  head?: RelationshipArrowType
+  tail?: RelationshipArrowType
+  line?: RelationshipLineType
+  color?: Color
+  links?: Array<string | { title?: string; url: string }>
+}
+
+export type Invalid<Message extends string> = Tagged<Message, 'Error'>
+export type Warn<Id, Existing> = IsLiteral<Existing> extends true ? Id extends Existing ? Invalid<'Already exists'> : Id
+  : Id
+
+/**
+ * Auxilary type to keep track of the types in builder
+ */
+export interface Types<
+  ElementKind extends string,
+  Fqn extends string,
+  ViewId extends string,
+  RelationshipKind extends string,
+  Tag extends string,
+  MetadataKey extends string
+> {
+  ElementKind: ElementKind
+  Fqn: Fqn
+  ViewId: ViewId
+  RelationshipKind: RelationshipKind
+  Tag: Tag
+  MetadataKey: MetadataKey
+
+  Tags: IfNever<Tag, never, [Tag, ...Tag[]]>
+  // Metadata: Metadata<MetadataKey>
+
+  NewElementProps: NewElementProps<Tag, Metadata<MetadataKey>>
+  NewRelationshipProps: NewRelationProps<RelationshipKind, Tag, Metadata<MetadataKey>>
+  NewViewProps: NewViewProps<Tag>
+}
+
+/**
+ * When building nested objects
+ */
+export interface TypesNested<
+  Parent extends string,
+  ElementKind extends string,
+  Fqn extends string,
+  ViewId extends string,
+  RelationshipKind extends string,
+  Tag extends string,
+  MetadataKey extends string
+> extends
+  Types<
+    ElementKind,
+    Fqn,
+    ViewId,
+    RelationshipKind,
+    Tag,
+    MetadataKey
+  >
+{
+  Parent: Parent
+}
+
+export type AnyTypes = Types<
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+>
+
+export type AnyTypesNested = TypesNested<
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+>
+
+export namespace Types {
+  export type FromSpecification<Spec> = Spec extends BuilderSpecification ? Types<
+      KeysOf<Spec['elements']>,
+      never,
+      never,
+      KeysOf<Spec['relationships']>,
+      TupleToUnion<Spec['tags']>,
+      TupleToUnion<Spec['metadataKeys']>
+    >
+    : never
+
+  export type AddFqn<T, Id extends string> = T extends TypesNested<infer P, any, any, any, any, any, any> ? TypesNested<
+      P,
+      T['ElementKind'],
+      `${P}.${Id}` | T['Fqn'],
+      T['ViewId'],
+      T['RelationshipKind'],
+      T['Tag'],
+      T['MetadataKey']
+    >
+    : T extends AnyTypes ? Types<
+        T['ElementKind'],
+        Id | T['Fqn'],
+        T['ViewId'],
+        T['RelationshipKind'],
+        T['Tag'],
+        T['MetadataKey']
+      >
+    : never
+
+  export type AddView<T, Id extends string> = T extends TypesNested<infer P, any, any, any, any, any, any>
+    ? TypesNested<
+      P,
+      T['ElementKind'],
+      T['Fqn'],
+      Id | T['ViewId'],
+      T['RelationshipKind'],
+      T['Tag'],
+      T['MetadataKey']
+    >
+    : T extends AnyTypes ? Types<
+        T['ElementKind'],
+        T['Fqn'],
+        Id | T['ViewId'],
+        T['RelationshipKind'],
+        T['Tag'],
+        T['MetadataKey']
+      >
+    : never
+
+  export type ToParsedLikeC4Model<T> = T extends AnyTypes ? ParsedLikeC4Model<
+      T['ElementKind'],
+      T['RelationshipKind'],
+      T['Tag'],
+      T['Fqn'],
+      T['ViewId']
+    >
+    : never
+}

package/src/builder/index.ts

@@ -0,0 +1,5 @@
+export type { AnyTypes, AnyTypesNested, BuilderSpecification, Types, TypesNested } from './_types'
+export { Builder } from './Builder'
+export type { ModelBuilder, ModelHelpers } from './Builder.model'
+export type { ViewBuilder, ViewHelpers } from './Builder.view'
+export type { ViewsBuilder } from './Builder.views'

package/src/index.ts

@@ -1,6 +1,10 @@
+export * from './builder'
+export { Builder } from './builder'
+export type * from './builder'
 export * from './colors'
 export * from './errors'
 export * from './model'
+
 export * from './types'
 export * from './utils/compare-natural'
 export * from './utils/fqn'

package/src/model/LikeC4DiagramModel.ts

@@ -15,11 +15,11 @@ import { type EdgeId, type ElementOrFqn, type Fqn, getId, type IncomingFilter, t
  * All methods are view-scoped, i.e. only return elements and connections in the view.
  */
 export class LikeC4DiagramModel {
-  private _rootElements = new Set<LikeC4DiagramModel.Element>()
+  private readonly _rootElements = new Set<LikeC4DiagramModel.Element>()
 
-  private _elements = new Map<Fqn, LikeC4DiagramModel.Element>()
+  private readonly _elements = new Map<Fqn, LikeC4DiagramModel.Element>()
 
-  private _connections: Map<EdgeId, LikeC4DiagramModel.Connection>
+  private readonly _connections: Map<EdgeId, LikeC4DiagramModel.Connection>
 
   constructor(
     public readonly view: DiagramView,
@@ -198,7 +198,7 @@ export namespace LikeC4DiagramModel {
   export class Element {
     constructor(
       public readonly node: DiagramNode,
-      private view: LikeC4DiagramModel
+      private readonly view: LikeC4DiagramModel
     ) {
     }
 
@@ -304,7 +304,7 @@ export namespace LikeC4DiagramModel {
   export class Connection {
     constructor(
       public readonly edge: DiagramEdge,
-      private view: LikeC4DiagramModel
+      private readonly view: LikeC4DiagramModel
     ) {
     }
 

package/src/model/LikeC4Model.ts

@@ -1,13 +1,13 @@
 import { isString, isTruthy, values } from 'remeda'
+import type { Class } from 'type-fest'
 import { nonNullable } from '../errors'
-import { DefaultElementShape, DefaultThemeColor } from '../types/element'
 import type {
   Element as C4Element,
   ElementKind as C4ElementKind,
   ElementShape as C4ElementShape,
-  Fqn as C4Fqn,
   Tag as C4Tag
 } from '../types/element'
+import { DefaultElementShape, DefaultThemeColor } from '../types/element'
 import type {
   ComputedLikeC4Model as C4ComputedLikeC4Model,
   LayoutedLikeC4Model as C4LayoutedLikeC4Model
@@ -17,8 +17,8 @@ import type { Color as C4Color } from '../types/theme'
 import { ancestorsFqn, commonAncestor, parentFqn } from '../utils/fqn'
 import { LikeC4DiagramModel } from './LikeC4DiagramModel'
 import { LikeC4ViewModel } from './LikeC4ViewModel'
-import { getId } from './types'
 import type { ElementOrFqn, Fqn, IncomingFilter, OutgoingFilter, RelationID, ViewID } from './types'
+import { getId } from './types'
 
 type PickBySource<Source> = Source extends LikeC4Model.Layouted.SourceModel ? LikeC4Model.Layouted
   : Source extends LikeC4Model.Computed.SourceModel ? LikeC4Model.Computed
@@ -48,47 +48,15 @@ export class LikeC4Model<M extends LikeC4Model.ViewModel = LikeC4Model.ViewModel
 
   private _cacheAscendingSiblings = new Map<Fqn, LikeC4Model.ElementModel<M>[]>()
 
-  private _views = new Map<Fqn, M>()
-
-  static create(source: LikeC4Model.SourceModel): PickBySource<typeof source> {
-    // static create<MM extends LikeC4Model>(source: MM['s']): PickBySource<typeof source> {
-    if (source.__ === 'layouted') {
-      return LikeC4Model.layouted(source)
-    }
-    return LikeC4Model.computed(source)
-  }
+  private _views: Map<Fqn, M>
 
-  static computed(source: C4ComputedLikeC4Model): LikeC4Model<LikeC4ViewModel> {
-    const instance = new LikeC4Model<LikeC4ViewModel>(
-      'computed',
-      source,
-      values(source.elements),
-      values(source.relations)
-    )
-    for (const view of values(source.views)) {
-      instance._views.set(view.id, new LikeC4ViewModel(view, instance))
-    }
-    return instance
-  }
-
-  static layouted(source: C4LayoutedLikeC4Model): LikeC4Model<LikeC4DiagramModel> {
-    const instance = new LikeC4Model<LikeC4DiagramModel>(
-      'layouted',
-      source,
-      values(source.elements),
-      values(source.relations)
-    )
-    for (const view of values(source.views)) {
-      instance._views.set(view.id, new LikeC4DiagramModel(view, instance))
-    }
-    return instance
-  }
-
-  protected constructor(
+  constructor(
     public readonly type: LikeC4Model.ModelType<M>,
     public readonly sourcemodel: LikeC4Model.SourceModel<M>,
     elements: C4Element[],
-    relations: C4Relation[]
+    relations: C4Relation[],
+    views: LikeC4Model.SourceModel<M>['views'],
+    ViewModelClass: Class<M>
   ) {
     for (const el of elements) {
       this.addElement(el)
@@ -96,6 +64,9 @@ export class LikeC4Model<M extends LikeC4Model.ViewModel = LikeC4Model.ViewModel
     for (const rel of relations) {
       this.addRelation(rel)
     }
+    this._views = new Map(
+      values(views).map(view => [view.id, new ViewModelClass(view, this)] as [Fqn, M])
+    )
   }
 
   /**
@@ -228,7 +199,7 @@ export class LikeC4Model<M extends LikeC4Model.ViewModel = LikeC4Model.ViewModel
     element: ElementOrFqn,
     filter: IncomingFilter = 'all'
   ): ReadonlyArray<LikeC4Model.ElementModel<M>> {
-    return this.incoming(element, filter).map(r => r.source)
+    return [...new Set(this.incoming(element, filter).map(r => r.source))]
   }
 
   /**
@@ -259,7 +230,7 @@ export class LikeC4Model<M extends LikeC4Model.ViewModel = LikeC4Model.ViewModel
     element: ElementOrFqn,
     filter: OutgoingFilter = 'all'
   ): ReadonlyArray<LikeC4Model.ElementModel<M>> {
-    return this.outgoing(element, filter).map(r => r.target)
+    return [...new Set(this.outgoing(element, filter).map(r => r.target))]
   }
 
   /**
@@ -380,6 +351,36 @@ export class LikeC4Model<M extends LikeC4Model.ViewModel = LikeC4Model.ViewModel
 }
 
 export namespace LikeC4Model {
+  export function create(source: LikeC4Model.SourceModel): PickBySource<typeof source> {
+    // static create<MM extends LikeC4Model>(source: MM['s']): PickBySource<typeof source> {
+    if (source.__ === 'layouted') {
+      return LikeC4Model.layouted(source)
+    }
+    return LikeC4Model.computed(source)
+  }
+
+  export function computed(source: C4ComputedLikeC4Model): LikeC4Model<LikeC4ViewModel> {
+    return new LikeC4Model(
+      'computed',
+      source,
+      values(source.elements),
+      values(source.relations),
+      source.views,
+      LikeC4ViewModel
+    )
+  }
+
+  export function layouted(source: C4LayoutedLikeC4Model): LikeC4Model<LikeC4DiagramModel> {
+    return new LikeC4Model(
+      'layouted',
+      source,
+      values(source.elements),
+      values(source.relations),
+      source.views,
+      LikeC4DiagramModel
+    )
+  }
+
   export function isModel(model: any): model is LikeC4Model {
     return model instanceof LikeC4Model
   }
@@ -389,6 +390,7 @@ export namespace LikeC4Model {
 
   export type ViewModel = LikeC4ViewModel | LikeC4DiagramModel
   export namespace ViewModel {
+    export type ElementModel = LikeC4ViewModel.Element | LikeC4DiagramModel.Element
     export type Relationship = LikeC4Model.Relationship<ViewModel>
 
     export function isLayouted(model: ViewModel): model is LikeC4DiagramModel {
@@ -416,10 +418,10 @@ export namespace LikeC4Model {
     return model.type === 'layouted'
   }
 
-  export class Relationship<M extends ViewModel> {
+  export class Relationship<M extends ViewModel = ViewModel> {
     constructor(
       public readonly relationship: C4Relation,
-      private model: LikeC4Model<M>
+      private readonly model: LikeC4Model<M>
     ) {
     }
 
@@ -459,10 +461,10 @@ export namespace LikeC4Model {
   }
 
   // Class renamed to ElementModel, otherwise generated DTS will be incorrect
-  export class ElementModel<M extends ViewModel> {
+  export class ElementModel<M extends ViewModel = ViewModel> {
     constructor(
       public readonly element: C4Element,
-      private model: LikeC4Model<M>
+      private readonly model: LikeC4Model<M>
     ) {
     }
 
@@ -528,6 +530,13 @@ export namespace LikeC4Model {
       return this.model.children(this)
     }
 
+    /**
+     * All views 'view of' current element
+     */
+    public viewsOf() {
+      return this.model.views().filter(v => v.viewOf?.id === this.id)
+    }
+
     /**
      * Views that contain this element
      */
@@ -555,6 +564,14 @@ export namespace LikeC4Model {
       return this.model.internal(this)
     }
 
+    /**
+     * Resolve siblings of the element and siblings of ancestors
+     *  (from closest to root)
+     */
+    public ascendingSiblings() {
+      return this.model.ascendingSiblings(this)
+    }
+
     // public *descendants(): IterableIterator<LikeC4Element> {
     //   return
     // }

package/src/model/LikeC4ViewModel.ts

@@ -14,11 +14,11 @@ import { type EdgeId, type ElementOrFqn, type Fqn, getId, type IncomingFilter, t
  * All methods are view-scoped, i.e. only return elements and connections in the view.
  */
 export class LikeC4ViewModel {
-  private _rootElements = new Set<LikeC4ViewModel.Element>()
+  private readonly _rootElements = new Set<LikeC4ViewModel.Element>()
 
-  private _elements = new Map<Fqn, LikeC4ViewModel.Element>()
+  private readonly _elements = new Map<Fqn, LikeC4ViewModel.Element>()
 
-  private _connections: Map<EdgeId, LikeC4ViewModel.Connection>
+  private readonly _connections: Map<EdgeId, LikeC4ViewModel.Connection>
 
   constructor(
     public readonly view: ComputedView,
@@ -151,7 +151,7 @@ export class LikeC4ViewModel {
     element: ElementOrFqn,
     filter: IncomingFilter = 'all'
   ): ReadonlyArray<LikeC4ViewModel.Element> {
-    return this.incoming(element, filter).map(r => r.source)
+    return [...new Set(this.incoming(element, filter).map(r => r.source))]
   }
 
   /**
@@ -180,7 +180,7 @@ export class LikeC4ViewModel {
     element: ElementOrFqn,
     filter: OutgoingFilter = 'all'
   ): ReadonlyArray<LikeC4ViewModel.Element> {
-    return this.outgoing(element, filter).map(r => r.target)
+    return [...new Set(this.outgoing(element, filter).map(r => r.target))]
   }
 }
 
@@ -192,7 +192,7 @@ export namespace LikeC4ViewModel {
   export class Element {
     constructor(
       public readonly node: ComputedNode,
-      private viewmodel: LikeC4ViewModel
+      private readonly viewmodel: LikeC4ViewModel
     ) {
     }
 
@@ -290,7 +290,7 @@ export namespace LikeC4ViewModel {
   export class Connection {
     constructor(
       public readonly edge: ComputedEdge,
-      private viewmodel: LikeC4ViewModel
+      private readonly viewmodel: LikeC4ViewModel
     ) {
     }
 

package/src/model/__test__/fixture.ts

@@ -248,6 +248,11 @@ const fakeRelationsArr = [
     target: 'cloud',
     title: 'uses'
   }),
+  rel({
+    source: 'customer',
+    target: 'cloud.frontend',
+    title: 'uses frontend'
+  }),
   rel({
     source: 'cloud.backend.graphql',
     target: 'cloud.backend.storage',

package/src/types/element.ts

@@ -1,9 +1,9 @@
-import type { Tagged } from 'type-fest'
+import type { IfNever, Tagged, TupleToUnion } from 'type-fest'
 import type { IconUrl, NonEmptyArray } from './_common'
 import type { Color, ThemeColor } from './theme'
 
 // Full-qualified-name
-export type Fqn = Tagged<string, 'Fqn'>
+export type Fqn<Id extends string = string> = Tagged<Id, 'Fqn'>
 
 export function AsFqn(name: string, parent?: Fqn | null) {
   return (parent ? parent + '.' + name : name) as Fqn
@@ -11,9 +11,9 @@ export function AsFqn(name: string, parent?: Fqn | null) {
 
 export const BorderStyles = ['solid', 'dashed', 'dotted', 'none'] as const
 
-export type BorderStyle = typeof BorderStyles[number]
+export type BorderStyle = TupleToUnion<typeof BorderStyles>
 
-export type ElementKind = Tagged<string, 'ElementKind'>
+export type ElementKind<Kinds extends string = string> = Tagged<Kinds, 'ElementKind'>
 export const ElementShapes = [
   'rectangle',
   'person',
@@ -24,7 +24,7 @@ export const ElementShapes = [
   'queue'
 ] as const
 
-export type ElementShape = typeof ElementShapes[number]
+export type ElementShape = TupleToUnion<typeof ElementShapes>
 export const DefaultThemeColor = 'primary' satisfies ThemeColor
 export const DefaultElementShape = 'rectangle' satisfies ElementShape
 
@@ -34,7 +34,7 @@ export interface ElementStyle {
   opacity?: number
 }
 
-export type Tag = Tagged<string, 'Tag'>
+export type Tag<Tags extends string = string> = Tagged<Tags, 'Tag'>
 
 export interface TagSpec {
   readonly id: Tag
@@ -49,20 +49,28 @@ export interface Link {
   readonly relative?: string
 }
 
-export interface Element {
-  readonly id: Fqn
-  readonly kind: ElementKind
+export interface TypedElement<
+  Ids extends string,
+  Kinds extends string,
+  Tags extends string,
+  MetadataKeys extends string = never
+> {
+  readonly id: Fqn<Ids>
+  readonly kind: ElementKind<Kinds>
   readonly title: string
   readonly description: string | null
   readonly technology: string | null
-  readonly tags: NonEmptyArray<Tag> | null
+  readonly tags: NonEmptyArray<Tag<Tags>> | null
   readonly links: NonEmptyArray<Link> | null
   readonly icon?: IconUrl
   readonly shape?: ElementShape
   readonly color?: Color
   readonly style?: ElementStyle
   readonly notation?: string
-  readonly metadata?: { [key: string]: string }
+  readonly metadata?: Record<MetadataKeys, string>
+}
+
+export interface Element extends TypedElement<string, string, string, string> {
 }
 
 export interface ElementKindSpecificationStyle {

package/src/types/model.ts

@@ -1,20 +1,25 @@
-import type { UnwrapTagged } from 'type-fest'
-import type { Element, ElementKind, ElementKindSpecification, Fqn, Tag } from './element'
+import type { ElementKindSpecification, Tag, TypedElement } from './element'
 import type { Relation, RelationID, RelationshipKindSpecification } from './relation'
 import type { ComputedView, DiagramView, LikeC4View, ViewID } from './view'
 
 /**
  * Parsed elements, relations, and views.
  */
-export interface ParsedLikeC4Model {
+export interface ParsedLikeC4Model<
+  ElementKinds extends string = string,
+  RelationKinds extends string = string,
+  Tags extends string = string,
+  Fqns extends string = string,
+  Views extends string = string
+> {
   specification: {
-    tags: Tag[]
-    elements: Record<UnwrapTagged<ElementKind>, ElementKindSpecification>
-    relationships: Record<UnwrapTagged<ElementKind>, RelationshipKindSpecification>
+    tags: Tag<Tags>[]
+    elements: Record<ElementKinds, ElementKindSpecification>
+    relationships: Record<RelationKinds, RelationshipKindSpecification>
   }
-  elements: Record<Fqn, Element>
+  elements: Record<Fqns, TypedElement<Fqns, ElementKinds, Tags>>
   relations: Record<RelationID, Relation>
-  views: Record<ViewID, LikeC4View>
+  views: Record<Views, LikeC4View<Views, Tags>>
 }
 
 /**

package/src/types/relation.ts

@@ -5,7 +5,7 @@ import type { Color, ThemeColor } from './theme'
 import type { ViewID } from './view'
 
 export type RelationID = Tagged<string, 'RelationID'>
-export type RelationshipKind = Tagged<string, 'RelationshipKind'>
+export type RelationshipKind<Kinds extends string = string> = Tagged<Kinds, 'RelationshipKind'>
 
 export type RelationshipLineType = 'dashed' | 'solid' | 'dotted'
 

package/src/types/view-changes.ts

@@ -1,7 +1,7 @@
 import type { NonEmptyArray } from './_common'
 import type { BorderStyle, ElementShape, Fqn } from './element'
 import type { ThemeColor } from './theme'
-import type { ViewManualLayout, ViewRuleAutoLayout } from './view'
+import type { AutoLayoutDirection, ViewManualLayout } from './view'
 
 export namespace ViewChange {
   export interface ChangeElementStyle {
@@ -22,7 +22,11 @@ export namespace ViewChange {
 
   export interface ChangeAutoLayout {
     op: 'change-autolayout'
-    layout: ViewRuleAutoLayout
+    layout: {
+      direction: AutoLayoutDirection
+      nodeSep?: number | null
+      rankSep?: number | null
+    }
   }
 }
 export type ViewChange = ViewChange.ChangeElementStyle | ViewChange.SaveManualLayout | ViewChange.ChangeAutoLayout