@likec4/core 1.17.1 → 1.19.0

package/src/types/expression-v2.ts

@@ -0,0 +1,172 @@
+import { invariant } from '../errors'
+import type { ExclusiveUnion } from './_common'
+import type { DeploymentRef as DeploymentModelRef, PredicateSelector } from './deployments'
+import type { Fqn } from './element'
+
+export namespace FqnRef {
+  /**
+   * Represents a reference to an instance within a deployment.
+   *
+   * @template D - The type representing the deployment fqn. Defaults to `Fqn`.
+   * @template M - The type representing the model fqn. Defaults to `Fqn`.
+   *
+   * @property {D} deployment - TThe fully qualified name (FQN) of the deployed instance.
+   * @property {M} element - The element reference within the deployment.
+   */
+  export type InsideInstanceRef<D = Fqn, M = Fqn> = {
+    deployment: D
+    element: M
+  }
+  export const isInsideInstanceRef = (ref: FqnRef): ref is InsideInstanceRef => {
+    return 'deployment' in ref && 'element' in ref
+  }
+
+  /**
+   * Represents a reference to a deployment element.
+   *
+   * @template F - The type of the fully qualified name (FQN) of the deployment element. Defaults to `Fqn`.
+   * @property {F} deployment - The fully qualified name (FQN) of the deployment element.
+   */
+  export type DeploymentElementRef<F = Fqn> = {
+    deployment: F
+  }
+  export const isDeploymentElementRef = (ref: FqnRef): ref is DeploymentElementRef => {
+    return 'deployment' in ref && !('element' in ref)
+  }
+
+  export type DeploymentRef<D = Fqn, M = Fqn> = DeploymentElementRef<D> | InsideInstanceRef<D, M>
+  export const isDeploymentRef = (ref: FqnRef): ref is DeploymentRef => {
+    return !isModelRef(ref)
+  }
+
+  /**
+   * Reference to logical model element
+   */
+  export type ModelRef<F = Fqn> = {
+    model: F
+  }
+  export const isModelRef = (ref: FqnRef): ref is ModelRef => {
+    return 'model' in ref
+  }
+
+  export const toDeploymentRef = (ref: FqnRef): DeploymentModelRef => {
+    invariant(isDeploymentRef(ref), 'Expected DeploymentRef')
+    return isInsideInstanceRef(ref)
+      ? {
+        id: ref.deployment,
+        element: ref.element,
+      }
+      : {
+        id: ref.deployment,
+      }
+  }
+}
+
+export type FqnRef<D = Fqn, M = Fqn> = ExclusiveUnion<{
+  InsideInstanceRef: FqnRef.InsideInstanceRef<D, M>
+  DeploymentRef: FqnRef.DeploymentRef<D>
+  ModelRef: FqnRef.ModelRef<M>
+}>
+
+export namespace FqnExpr {
+  export type Wildcard = {
+    wildcard: true
+  }
+  export const isWildcard = (expr: ExpressionV2): expr is Wildcard => {
+    return 'wildcard' in expr && expr.wildcard === true
+  }
+
+  export type ModelRef<M = Fqn> = {
+    ref: FqnRef.ModelRef<M>
+    selector?: PredicateSelector
+  }
+  export const isModelRef = (ref: ExpressionV2): ref is ModelRef => {
+    return 'ref' in ref && FqnRef.isModelRef(ref.ref)
+  }
+
+  export type DeploymentRef<D = Fqn, M = Fqn> = {
+    ref: FqnRef.DeploymentRef<D> | FqnRef.InsideInstanceRef<D, M>
+    selector?: PredicateSelector
+  }
+  export const isDeploymentRef = (ref: ExpressionV2): ref is FqnExpr.DeploymentRef => {
+    return 'ref' in ref && FqnRef.isDeploymentRef(ref.ref)
+  }
+
+  export type NonWildcard<D = Fqn, M = Fqn> = ExclusiveUnion<{
+    ModelRef: ModelRef<M>
+    DeploymentRef: DeploymentRef<D, M>
+  }>
+}
+
+export type FqnExpr<D = Fqn, M = Fqn> = ExclusiveUnion<{
+  Wildcard: FqnExpr.Wildcard
+  ModelRef: FqnExpr.ModelRef<M>
+  DeploymentRef: FqnExpr.DeploymentRef<D, M>
+}>
+
+export namespace RelationExpr {
+  export type Direct<D = Fqn, M = Fqn> = {
+    source: FqnExpr<D, M>
+    target: FqnExpr<D, M>
+    isBidirectional?: boolean
+  }
+  export const isDirect = (expr: ExpressionV2): expr is Direct => {
+    return 'source' in expr && 'target' in expr
+  }
+  export type Incoming<D = Fqn, M = Fqn> = {
+    incoming: FqnExpr<D, M>
+  }
+  export const isIncoming = (expr: ExpressionV2): expr is Incoming => {
+    return 'incoming' in expr
+  }
+  export type Outgoing<D = Fqn, M = Fqn> = {
+    outgoing: FqnExpr<D, M>
+  }
+  export const isOutgoing = (expr: ExpressionV2): expr is Outgoing => {
+    return 'outgoing' in expr
+  }
+  export type InOut<D = Fqn, M = Fqn> = {
+    inout: FqnExpr<D, M>
+  }
+  export const isInOut = (expr: ExpressionV2): expr is InOut => {
+    return 'inout' in expr
+  }
+}
+
+export type RelationExpr<D = Fqn, M = Fqn> = ExclusiveUnion<{
+  Direct: RelationExpr.Direct<D, M>
+  Incoming: RelationExpr.Incoming<D, M>
+  Outgoing: RelationExpr.Outgoing<D, M>
+  InOut: RelationExpr.InOut<D, M>
+}>
+
+/**
+ * Represents a version 2 expression which can be one of several types.
+ *
+ * @template D - The type for the deployment FQN, defaults to `Fqn`.
+ * @template M - The type for the model FQN, defaults to `Fqn`.
+ */
+export type ExpressionV2<D = Fqn, M = Fqn> = ExclusiveUnion<{
+  Wildcard: FqnExpr.Wildcard
+  ModelRef: FqnExpr.ModelRef<M>
+  DeploymentRef: FqnExpr.DeploymentRef<D, M>
+  Direct: RelationExpr.Direct<D, M>
+  Incoming: RelationExpr.Incoming<D, M>
+  Outgoing: RelationExpr.Outgoing<D, M>
+  InOut: RelationExpr.InOut<D, M>
+}>
+
+export namespace ExpressionV2 {
+  export const isFqnExpr = (expr: ExpressionV2): expr is FqnExpr => {
+    return FqnExpr.isWildcard(expr)
+      || FqnExpr.isModelRef(expr)
+      || FqnExpr.isDeploymentRef(expr)
+  }
+
+  export const isRelation = (expr: ExpressionV2): expr is RelationExpr => {
+    return RelationExpr.isDirect(expr)
+      || RelationExpr.isIncoming(expr)
+      || RelationExpr.isOutgoing(expr)
+      || RelationExpr.isInOut(expr)
+  }
+}

package/src/types/expression.ts

@@ -3,7 +3,7 @@ import type { BorderStyle, ElementKind, ElementShape, Fqn, Tag } from './element
 import type { WhereOperator } from './operators'
 import type { RelationshipArrowType, RelationshipLineType } from './relation'
 import type { Color } from './theme'
-import type { ViewID } from './view'
+import type { ViewId } from './view'
 
 interface BaseExpr {
   where?: never
@@ -13,7 +13,8 @@ interface BaseExpr {
   elementKind?: never
   elementTag?: never
   isEqual?: never
-  isDescedants?: never
+  isChildren?: never
+  isDescendants?: never
   wildcard?: never
   source?: never
   target?: never
@@ -23,9 +24,10 @@ interface BaseExpr {
   customRelation?: never
 }
 
-export interface ElementRefExpr extends Omit<BaseExpr, 'element' | 'isDescedants'> {
+export interface ElementRefExpr extends Omit<BaseExpr, 'element' | 'isChildren' | 'isDescendants'> {
   element: Fqn
-  isDescedants?: boolean
+  isChildren?: boolean
+  isDescendants?: boolean
 }
 export function isElementRef(expr: Expression): expr is ElementRefExpr {
   return 'element' in expr
@@ -50,7 +52,7 @@ export interface CustomElementExpr extends Omit<BaseExpr, 'custom'> {
     icon?: IconUrl
     border?: BorderStyle
     opacity?: number
-    navigateTo?: ViewID
+    navigateTo?: ViewId
   }
 }
 
@@ -80,12 +82,16 @@ export function isElementTagExpr(expr: Expression): expr is ElementTagExpr {
   return 'elementTag' in expr && 'isEqual' in expr
 }
 
-export type ElementExpression =
+export type NonWilcard =
   | ElementRefExpr
-  | WildcardExpr
   | ElementKindExpr
   | ElementTagExpr
   | ExpandedElementExpr
+
+export type ElementExpression =
+  | NonWilcard
+  | WildcardExpr
+
 export function isElement(expr: Expression): expr is ElementExpression {
   return isElementRef(expr)
     || isWildcard(expr)
@@ -109,12 +115,12 @@ export function isElementPredicateExpr(expr: Expression): expr is ElementPredica
   return isElement(expr) || isElementWhere(expr) || isCustomElement(expr)
 }
 
-export interface RelationExpr extends Omit<BaseExpr, 'source' | 'target'> {
+export interface DirectRelationExpr extends Omit<BaseExpr, 'source' | 'target'> {
   source: ElementExpression
   target: ElementExpression
   isBidirectional?: boolean
 }
-export function isRelation(expr: Expression): expr is RelationExpr {
+export function isRelation(expr: Expression): expr is DirectRelationExpr {
   return 'source' in expr && 'target' in expr
 }
 
@@ -138,7 +144,7 @@ export function isOutgoing(expr: Expression): expr is OutgoingExpr {
   return 'outgoing' in expr
 }
 
-export type RelationExpression = RelationExpr | InOutExpr | IncomingExpr | OutgoingExpr
+export type RelationExpression = DirectRelationExpr | InOutExpr | IncomingExpr | OutgoingExpr
 
 export function isRelationExpression(expr: Expression): expr is RelationExpression {
   return isRelation(expr) || isInOut(expr) || isIncoming(expr) || isOutgoing(expr)
@@ -162,7 +168,7 @@ export interface CustomRelationExpr extends Omit<BaseExpr, 'customRelation'> {
     technology?: string
     notation?: string
     // Link to dynamic view
-    navigateTo?: ViewID
+    navigateTo?: ViewId
     // Notes for walkthrough
     notes?: string
     color?: Color

package/src/types/global.ts

@@ -13,7 +13,7 @@ export type GlobalStyleID = Tagged<string, 'GlobalStyleID'>
 export type GlobalStyles = NonEmptyTuple<ViewRuleStyle>
 
 export interface ModelGlobals {
-  predicates: Record<GlobalPredicateId, GlobalPredicates>
-  dynamicPredicates: Record<GlobalPredicateId, GlobalDynamicPredicates>
-  styles: Record<GlobalStyleID, GlobalStyles>
+  readonly predicates: Record<GlobalPredicateId, GlobalPredicates>
+  readonly dynamicPredicates: Record<GlobalPredicateId, GlobalDynamicPredicates>
+  readonly styles: Record<GlobalStyleID, GlobalStyles>
 }

package/src/types/index.ts

@@ -1,12 +1,220 @@
-export * from './_common'
-export * from './element'
-export * from './expression'
-export * from './global'
-export * from './model'
-export * from './operators'
-export * from './overview-graph'
-export * from './relation'
-export * from './theme'
-export * from './view'
-export * from './view-changes'
-export * from './view-notation'
+export type {
+  CustomColor,
+  ExclusiveUnion,
+  IconUrl,
+  IteratorLike,
+  KeysOf,
+  NonEmptyArray,
+  NonEmptyReadonlyArray,
+  NTuple,
+  Point,
+  Predicate,
+  XYPoint,
+} from './_common'
+
+export { DeploymentElement } from './deployments'
+export type {
+  DeployedInstance,
+  DeploymentElementStyle,
+  DeploymentNode,
+  DeploymentNodeKind,
+  DeploymentNodeKindSpecification,
+  DeploymentRef,
+  DeploymentRelation,
+  PredicateSelector,
+} from './deployments'
+
+export {
+  AsFqn,
+  BorderStyles,
+  DefaultElementShape,
+  DefaultThemeColor,
+  ElementKind,
+  ElementShapes,
+} from './element'
+export type {
+  BorderStyle,
+  Element,
+  ElementKindSpecification,
+  ElementKindSpecificationStyle,
+  ElementShape,
+  ElementStyle,
+  Fqn,
+  Link,
+  Tag,
+  TagSpec,
+  TypedElement,
+} from './element'
+
+export {
+  isCustomElement,
+  isCustomRelationExpr,
+  isElement,
+  isElementKindExpr,
+  isElementPredicateExpr,
+  isElementRef,
+  isElementTagExpr,
+  isElementWhere,
+  isExpandedElementExpr,
+  isIncoming,
+  isInOut,
+  isOutgoing,
+  isRelation,
+  isRelationExpression,
+  isRelationPredicateExpr,
+  isRelationWhere,
+  isWildcard,
+} from './expression'
+export type {
+  CustomElementExpr,
+  CustomRelationExpr,
+  DirectRelationExpr,
+  ElementExpression,
+  ElementKindExpr,
+  ElementPredicateExpression,
+  ElementRefExpr,
+  ElementTagExpr,
+  ElementWhereExpr,
+  ExpandedElementExpr,
+  Expression,
+  IncomingExpr,
+  InOutExpr,
+  NonWilcard,
+  OutgoingExpr,
+  RelationExpression,
+  RelationPredicateExpression,
+  RelationWhereExpr,
+  WildcardExpr,
+} from './expression'
+
+export { ExpressionV2, FqnExpr, FqnRef, RelationExpr } from './expression-v2'
+
+export type {
+  GlobalDynamicPredicates,
+  GlobalPredicateId,
+  GlobalPredicates,
+  GlobalStyleID,
+  GlobalStyles,
+  ModelGlobals,
+} from './global'
+
+export type {
+  AnyParsedLikeC4Model,
+  ComputedLikeC4Model,
+  GenericLikeC4Model,
+  LayoutedLikeC4Model,
+  LikeC4ModelDump,
+  ParsedLikeC4Model,
+} from './model'
+
+export {
+  isAndOperator,
+  isKindEqual,
+  isNotOperator,
+  isOrOperator,
+  isTagEqual,
+  whereOperatorAsPredicate,
+} from './operators'
+export type {
+  AndOperator,
+  EqualOperator,
+  Filterable,
+  KindEqual,
+  NotOperator,
+  OrOperator,
+  TagEqual,
+  WhereOperator,
+} from './operators'
+export type { OverviewGraph } from './overview-graph'
+export { DefaultArrowType, DefaultLineStyle, DefaultRelationshipColor } from './relation'
+export type {
+  AbstractRelation,
+  ModelRelation,
+  RelationId,
+  RelationshipArrowType,
+  RelationshipKind,
+  RelationshipKindSpecification,
+  RelationshipLineType,
+} from './relation'
+export { isThemeColor } from './theme'
+export type {
+  Color,
+  ColorLiteral,
+  ElementThemeColors,
+  ElementThemeColorValues,
+  HexColorLiteral,
+  LikeC4Theme,
+  RelationshipThemeColors,
+  RelationshipThemeColorValues,
+  ThemeColor,
+  ThemeColorValues,
+} from './theme'
+export {
+  ComputedNode, // namespace
+  ComputedView, // namespace
+  DiagramNode, // namespace
+  extractStep,
+  getBBoxCenter,
+  getParallelStepsPrefix,
+  isAutoLayoutDirection,
+  isDeploymentView,
+  isDynamicView,
+  isDynamicViewParallelSteps,
+  isElementView,
+  isExtendsElementView,
+  isScopedElementView,
+  isStepEdgeId,
+  isViewRuleAutoLayout,
+  isViewRuleGlobalPredicateRef,
+  isViewRuleGlobalStyle,
+  isViewRuleGroup,
+  isViewRulePredicate,
+  isViewRuleStyle,
+  stepEdgeId,
+} from './view'
+export type {
+  AutoLayoutDirection,
+  BasicElementView,
+  BasicView,
+  BBox,
+  ComputedDeploymentView,
+  ComputedDynamicView,
+  ComputedEdge,
+  ComputedElementView,
+  CustomColorDefinitions,
+  DeploymentView,
+  DeploymentViewRule,
+  DeploymentViewRulePredicate,
+  DeploymentViewRuleStyle,
+  DiagramEdge,
+  DiagramView,
+  DynamicView,
+  DynamicViewIncludeRule,
+  DynamicViewParallelSteps,
+  DynamicViewRule,
+  DynamicViewStep,
+  DynamicViewStepOrParallel,
+  EdgeId,
+  ElementView,
+  ExtendsElementView,
+  LikeC4View,
+  NodeId,
+  ScopedElementView,
+  StepEdgeId,
+  StepEdgeIdLiteral,
+  ViewAutoLayout,
+  ViewId,
+  ViewManualLayout,
+  ViewRule,
+  ViewRuleAutoLayout,
+  ViewRuleGlobalPredicateRef,
+  ViewRuleGlobalStyle,
+  ViewRuleGroup,
+  ViewRulePredicate,
+  ViewRuleStyle,
+  ViewRuleStyleOrGlobalRef,
+  ViewWithHash,
+  ViewWithNotation,
+} from './view'
+export type { ViewChange } from './view-changes'
+export type { ElementNotation } from './view-notation'

package/src/types/model.ts

@@ -1,41 +1,104 @@
+import type {
+  DeploymentElement,
+  DeploymentNodeKind,
+  DeploymentNodeKindSpecification,
+  DeploymentRelation
+} from './deployments'
 import type { ElementKindSpecification, Tag, TypedElement } from './element'
 import type { ModelGlobals } from './global'
-import type { Relation, RelationID, RelationshipKindSpecification } from './relation'
-import type { ComputedView, DiagramView, LikeC4View, ViewID } from './view'
+import type { ModelRelation, RelationId, RelationshipKindSpecification } from './relation'
+import type { ComputedView, DiagramView, LikeC4View } from './view'
 
 /**
- * Parsed elements, relations, and views.
+ * Represents a LikeC4 model with customizable type parameters,
+ * parsed from DSL or result from Builder
+ *
+ * !IMPORTANT: This is a low-level type, use `LikeC4Model` instead.
+ * !NOTE: Views are not computed yet.
+ *
+ * @typeParam ElementKinds - Types of elements in the model (defaults to string)
+ * @typeParam RelationKinds - Types of relationships (defaults to string)
+ * @typeParam Tags - Types of tags that can be applied (defaults to string)
+ * @typeParam Fqns - Fully Qualified Names for elements (defaults to string)
+ * @typeParam Views - Types of views in the model (defaults to string)
+ * @typeParam DeploymentFqns - Fully Qualified Names for deployment nodes (defaults to string)
  */
 export interface ParsedLikeC4Model<
   ElementKinds extends string = string,
   RelationKinds extends string = string,
   Tags extends string = string,
   Fqns extends string = string,
-  Views extends string = string
+  Views extends string = string,
+  DeploymentFqns extends string = string
 > {
+  // To prevent accidental use of this type
+  __?: never
   specification: {
     tags: Tag<Tags>[]
     elements: Record<ElementKinds, ElementKindSpecification>
+    deployments: Record<DeploymentNodeKind, DeploymentNodeKindSpecification>
     relationships: Record<RelationKinds, RelationshipKindSpecification>
   }
   elements: Record<Fqns, TypedElement<Fqns, ElementKinds, Tags>>
-  relations: Record<RelationID, Relation>
+  relations: Record<RelationId, ModelRelation>
   globals: ModelGlobals
   views: Record<Views, LikeC4View<Views, Tags>>
+  /**
+   * Deployment Model.
+   */
+  deployments: {
+    elements: Record<DeploymentFqns, DeploymentElement>
+    relations: Record<RelationId, DeploymentRelation>
+  }
 }
 
+export type AnyParsedLikeC4Model = ParsedLikeC4Model<any, any, any, any, any, any>
 /**
- * Same as `ParsedLikeC4Model` but with computed views.
+ * Hook to get types from dump
  */
-export interface ComputedLikeC4Model extends Omit<ParsedLikeC4Model, 'views'> {
-  __?: never
-  views: Record<ViewID, ComputedView>
+export type LikeC4ModelDump = {
+  elements: {
+    [kind: string]: object
+  }
+  deployments: {
+    elements: {
+      [kind: string]: object
+    }
+  }
+  views: {
+    [kind: string]: object
+  }
 }
 
 /**
- * Same as `ParsedLikeC4Model` but with layouted views (DiagramView)
+ * Same as {@link ParsedLikeC4Model}, but with computed views or layouted views.
  */
-export interface LayoutedLikeC4Model extends Omit<ParsedLikeC4Model, 'views'> {
+export interface GenericLikeC4Model<
+  Fqns extends string = string,
+  DeploymentFqns extends string = string,
+  Views extends string = string,
+  Tags extends string = string,
+  T = 'computed' | 'layouted'
+> extends Omit<ParsedLikeC4Model<string, string, Tags, Fqns, Views, DeploymentFqns>, 'views' | '__'> {
+  __?: T
+  views: Record<Views, ComputedView<Views> | DiagramView<Views>>
+}
+
+export interface ComputedLikeC4Model<
+  Fqns extends string = string,
+  DeploymentFqns extends string = string,
+  Views extends string = string,
+  Tags extends string = string
+> extends Omit<GenericLikeC4Model<Fqns, DeploymentFqns, Views, Tags, 'computed'>, 'views'> {
+  views: Record<Views, ComputedView<Views>>
+}
+
+export interface LayoutedLikeC4Model<
+  Fqns extends string = string,
+  DeploymentFqns extends string = string,
+  Views extends string = string,
+  Tags extends string = string
+> extends Omit<GenericLikeC4Model<Fqns, DeploymentFqns, Views, Tags, 'layouted'>, 'views'> {
   __: 'layouted'
-  views: Record<ViewID, DiagramView>
+  views: Record<Views, DiagramView<Views, Tags>>
 }

package/src/types/operators.ts

@@ -64,7 +64,7 @@ export type Filterable<
   FTag extends string = string,
   FKind extends string = string
 > = {
-  tags?: FTag[] | null
+  tags?: readonly FTag[] | null
   kind?: FKind
 }
 

package/src/types/overview-graph.ts

@@ -1,5 +1,5 @@
 import type { NonEmptyArray, Point, XYPoint } from './_common'
-import type { BBox, ViewID } from './view'
+import type { BBox, ViewId } from './view'
 
 /**
  * OverviewGraph is a graph representation of all views in a model
@@ -17,7 +17,7 @@ export namespace OverviewGraph {
   } | {
     id: string
     type: 'view'
-    viewId: ViewID
+    viewId: ViewId
     label: string
     parentId: string | null
     position: XYPoint