@likec4/core 1.30.0 → 1.32.0

package/src/types/model-dump.ts

@@ -0,0 +1,72 @@
+import type { KeysOf } from './_common'
+import type * as aux from './aux'
+import type { _stage } from './const'
+import type { ParsedLikeC4ModelData } from './model-data'
+
+/**
+ * JSON representation of {@link Specification}
+ */
+export interface SpecificationDump {
+  elements: {
+    [kind: string]: object
+  }
+  tags?: {
+    [tag: string]: object
+  }
+  deployments?: {
+    [kind: string]: object
+  }
+  relationships?: {
+    [kind: string]: object
+  }
+  metadataKeys?: string[]
+  customColors?: {
+    [kind: string]: object
+  }
+}
+export type SpecTypesFromDump<J> = J extends SpecificationDump ? aux.SpecAux<
+    KeysOf<J['elements']>,
+    KeysOf<J['deployments']>,
+    KeysOf<J['relationships']>,
+    KeysOf<J['tags']>,
+    J['metadataKeys'] extends readonly [string, ...string[]] ? J['metadataKeys'][number] : never
+  >
+  : aux.SpecAux<never, never, never, never, never>
+
+/**
+ * Dump differs from {@link ParsedLikeC4ModelData} by the fact that it is computed or layouted
+ */
+export type LikeC4ModelDump = {
+  [_stage]?: 'computed' | 'layouted'
+  projectId?: string
+  specification: SpecificationDump
+  elements?: {
+    [kind: string]: object
+  }
+  deployments: {
+    elements?: {
+      [kind: string]: object
+    }
+    relations?: {}
+  }
+  views?: {
+    [kind: string]: object
+  }
+  relations?: {}
+  globals?: {
+    predicates?: {}
+    dynamicPredicates?: {}
+    styles?: {}
+  }
+  imports?: {}
+}
+
+export type AuxFromDump<D> = D extends LikeC4ModelDump ? aux.Aux<
+    D[_stage] extends infer S extends string & 'computed' | 'layouted' ? S : 'computed' | 'layouted' | 'parsed',
+    KeysOf<D['elements']>,
+    KeysOf<D['deployments']['elements']>,
+    KeysOf<D['views']>,
+    D['projectId'] extends infer P extends string ? P : never,
+    SpecTypesFromDump<D['specification']>
+  >
+  : aux.Never

package/src/types/model-logical.ts

@@ -0,0 +1,111 @@
+import type { Link } from './_common'
+import type * as aux from './aux'
+import type { AnyAux } from './aux'
+import type { FqnRef } from './fqnRef'
+import type * as scalar from './scalar'
+import type {
+  BorderStyle,
+  Color,
+  ElementShape,
+  RelationshipArrowType,
+  RelationshipLineType,
+  ShapeSize,
+  SpacingSize,
+  TextSize,
+  ThemeColor,
+} from './styles'
+
+export const DefaultThemeColor: ThemeColor = 'primary'
+export const DefaultElementShape: ElementShape = 'rectangle'
+export const DefaultShapeSize: ShapeSize = 'md'
+export const DefaultPaddingSize: SpacingSize = 'md'
+export const DefaultTextSize: TextSize = 'md'
+
+export interface ElementStyle {
+  readonly border?: BorderStyle
+  /**
+   * In percentage 0-100, 0 is fully transparent
+   *
+   * @default 100
+   */
+  readonly opacity?: number
+  /**
+   * If true, the element is rendered as multiple shapes
+   * @default false
+   */
+  readonly multiple?: boolean
+
+  /**
+   * Shape size
+   *
+   * @default 'md'
+   */
+  readonly size?: ShapeSize
+
+  readonly padding?: SpacingSize
+
+  readonly textSize?: TextSize
+}
+
+// dprint-ignore
+export interface Element<A extends AnyAux = AnyAux>
+  extends
+    aux.WithOptionalTags<A>,
+    aux.WithOptionalLinks,
+    aux.WithMetadata<A>
+{
+  readonly id: aux.StrictFqn<A>
+  readonly kind: aux.ElementKind<A>
+  readonly title: string
+  readonly description?: string | null
+  readonly technology?: string | null
+  readonly tags?: aux.Tags<A> | null
+  readonly links?: readonly Link[] | null
+  readonly icon?: scalar.Icon
+  readonly shape?: ElementShape
+  readonly color?: Color
+  readonly style?: ElementStyle
+  readonly notation?: string
+  readonly metadata?: aux.Metadata<A>
+}
+
+export const DefaultLineStyle: RelationshipLineType = 'dashed'
+export const DefaultArrowType: RelationshipArrowType = 'normal'
+export const DefaultRelationshipColor: ThemeColor = 'gray'
+
+// dprint-ignore
+export interface AbstractRelationship<A extends AnyAux>
+  extends
+    aux.WithOptionalTags<A>,
+    aux.WithOptionalLinks,
+    aux.WithMetadata<A>
+{
+  readonly id: scalar.RelationId
+  readonly title?: string | null
+  readonly description?: string | null
+  readonly technology?: string | null
+  readonly kind?: aux.RelationKind<A>
+  readonly color?: Color
+  readonly line?: RelationshipLineType
+  readonly head?: RelationshipArrowType
+  readonly tail?: RelationshipArrowType
+  readonly tags?: aux.Tags<A> | null
+  readonly links?: readonly Link[] | null
+  // Link to dynamic view
+  readonly navigateTo?: aux.ViewId<A>
+  readonly metadata?: aux.Metadata<A>
+}
+
+/**
+ * Relationship between two model elements
+ */
+export interface Relationship<A extends AnyAux = AnyAux> extends AbstractRelationship<A> {
+  readonly source: FqnRef.ModelRef<A>
+  readonly target: FqnRef.ModelRef<A>
+}
+
+/**
+ * Backward compatibility alias
+ * @deprecated Use {@link Relationship} instead
+ */
+export type ModelRelation<A extends AnyAux = AnyAux> = Relationship<A>

package/src/types/model-spec.ts

@@ -0,0 +1,81 @@
+import type { IsNever } from 'type-fest'
+import type * as aux from './aux'
+import type { Any } from './aux'
+import type * as scalar from './scalar'
+import type {
+  Icon,
+} from './scalar'
+import type {
+  BorderStyle,
+  Color,
+  ColorLiteral,
+  CustomColorDefinitions,
+  ElementShape,
+  RelationshipArrowType,
+  RelationshipLineType,
+  ShapeSize,
+  SpacingSize,
+  TextSize,
+  ThemeColor,
+} from './styles'
+
+/**
+ * Element and deployment kind specification
+ */
+export interface ElementSpecification {
+  tags?: scalar.Tag[]
+  technology?: string
+  notation?: string
+  style: {
+    shape?: ElementShape
+    icon?: Icon
+    color?: Color
+    border?: BorderStyle
+    opacity?: number
+    size?: ShapeSize
+    padding?: SpacingSize
+    textSize?: TextSize
+    multiple?: boolean
+  }
+}
+
+export interface TagSpecification {
+  color: ThemeColor | ColorLiteral
+}
+
+/**
+ * Checks if tag color is defined in the specification
+ * Expects HEX, `rgb(...)` or `rgba(...)` color
+ */
+export function isTagColorSpecified(spec: string | TagSpecification): spec is { color: ColorLiteral } {
+  const color = typeof spec === 'string' ? spec : spec.color
+  return color.startsWith('#') || color.startsWith('rgb')
+}
+
+export interface RelationshipSpecification {
+  technology?: string
+  notation?: string
+  color?: Color
+  line?: RelationshipLineType
+  head?: RelationshipArrowType
+  tail?: RelationshipArrowType
+}
+
+export type Specification<A> = A extends Any ? {
+    tags: {
+      [key in aux.Tag<A>]: TagSpecification
+    }
+    elements: {
+      [key in aux.ElementKind<A>]: Partial<ElementSpecification>
+    }
+    deployments: {
+      [key in aux.DeploymentKind<A>]: Partial<ElementSpecification>
+    }
+    relationships: {
+      [key in aux.RelationKind<A>]: Partial<RelationshipSpecification>
+    }
+    // dprint-ignore
+    metadataKeys?: IsNever<aux.MetadataKey<A>> extends true ? never : aux.MetadataKey<A>[]
+    customColors?: CustomColorDefinitions
+  } :
+  never

package/src/types/operators.ts

@@ -1,6 +1,8 @@
-import { allPass, anyPass, isNot, isNullish } from 'remeda'
-import { nonexhaustive } from '../errors'
+import { allPass, anyPass, isNot, isNullish, isString } from 'remeda'
+import { nonexhaustive } from '../utils/invariant'
 import type { NonEmptyArray } from './_common'
+import type * as aux from './aux'
+import type { Any } from './aux'
 
 export type EqualOperator<V> = {
   eq: V
@@ -10,85 +12,82 @@ export type EqualOperator<V> = {
   neq: V
 }
 
-export type AllNever = {
+type AllNever = {
   not?: never
   and?: never
   or?: never
   tag?: never
   kind?: never
   participant?: never
+  operator?: never
 }
 
-export type TagEqual<Tag> = Omit<AllNever, 'tag'> & {
-  tag: EqualOperator<Tag>
+export type TagEqual<A extends Any> = Omit<AllNever, 'tag'> & {
+  tag: EqualOperator<aux.Tag<A>> | aux.Tag<A>
 }
-export const isTagEqual = <Tag>(operator: WhereOperator<Tag, any>): operator is TagEqual<Tag> => {
+export function isTagEqual<A extends Any>(operator: WhereOperator<A>): operator is TagEqual<A> {
   return 'tag' in operator
 }
 
-export type KindEqual<Kind> = Omit<AllNever, 'kind'> & {
-  kind: EqualOperator<Kind>
+export type KindEqual<A extends Any> = Omit<AllNever, 'kind'> & {
+  kind: EqualOperator<aux.AllKinds<A>> | aux.AllKinds<A>
 }
-export const isKindEqual = <Kind>(operator: WhereOperator<any, Kind>): operator is KindEqual<Kind> => {
+export function isKindEqual<A extends Any>(operator: WhereOperator<A>): operator is KindEqual<A> {
   return 'kind' in operator
 }
 
 export type Participant = 'source' | 'target'
-export type ParticipantOperator<Tag, Kind> = Omit<AllNever, 'participant'> & {
+export type ParticipantOperator<A extends Any> = Omit<AllNever, 'participant' | 'operator'> & {
   participant: Participant
-  operator: KindEqual<Kind> | TagEqual<Tag>
+  operator: KindEqual<A> | TagEqual<A>
 }
-export const isParticipantOperator = <Tag, Kind>(
-  operator: WhereOperator<Tag, any>,
-): operator is ParticipantOperator<Tag, Kind> => {
+export function isParticipantOperator<A extends Any>(
+  operator: WhereOperator<A>,
+): operator is ParticipantOperator<A> {
   return 'participant' in operator
 }
 
-export type NotOperator<Tag, Kind> = Omit<AllNever, 'not'> & {
-  not: WhereOperator<Tag, Kind>
+export type NotOperator<A extends Any> = Omit<AllNever, 'not'> & {
+  not: WhereOperator<A>
 }
-export const isNotOperator = <Tag, Kind>(operator: WhereOperator<Tag, Kind>): operator is NotOperator<Tag, Kind> => {
+export function isNotOperator<A extends Any>(operator: WhereOperator<A>): operator is NotOperator<A> {
   return 'not' in operator
 }
 
-export type AndOperator<Tag, Kind> = Omit<AllNever, 'and'> & {
-  and: NonEmptyArray<WhereOperator<Tag, Kind>>
+export type AndOperator<A extends Any> = Omit<AllNever, 'and'> & {
+  and: NonEmptyArray<WhereOperator<A>>
 }
-export const isAndOperator = <Tag, Kind>(operator: WhereOperator<Tag, Kind>): operator is AndOperator<Tag, Kind> => {
+export function isAndOperator<A extends Any>(operator: WhereOperator<A>): operator is AndOperator<A> {
   return 'and' in operator
 }
 
-export type OrOperator<Tag, Kind> = Omit<AllNever, 'or'> & {
-  or: NonEmptyArray<WhereOperator<Tag, Kind>>
+export type OrOperator<A extends Any> = Omit<AllNever, 'or'> & {
+  or: NonEmptyArray<WhereOperator<A>>
 }
-export const isOrOperator = <Tag, Kind>(operator: WhereOperator<Tag, Kind>): operator is OrOperator<Tag, Kind> => {
+export function isOrOperator<A extends Any>(operator: WhereOperator<A>): operator is OrOperator<A> {
   return 'or' in operator
 }
 
-export type WhereOperator<Tag, Kind> =
-  | TagEqual<Tag>
-  | KindEqual<Kind>
-  | ParticipantOperator<Tag, Kind>
-  | NotOperator<Tag, Kind>
-  | AndOperator<Tag, Kind>
-  | OrOperator<Tag, Kind>
+export type WhereOperator<A extends Any = Any> =
+  | TagEqual<A>
+  | KindEqual<A>
+  | ParticipantOperator<A>
+  | NotOperator<A>
+  | AndOperator<A>
+  | OrOperator<A>
 
-export type Filterable<
-  FTag extends string | null = string | null,
-  FKind extends string | null = string | null,
-> = {
-  tags?: readonly FTag[] | null
-  kind?: FKind
-  source?: Filterable<FTag, FKind>
-  target?: Filterable<FTag, FKind>
+export type Filterable<A extends Any> = {
+  tags?: aux.Tags<A> | null | undefined
+  kind?: aux.AllKinds<A> | null | undefined
+  source?: Filterable<A>
+  target?: Filterable<A>
 }
 
-export type OperatorPredicate<V extends Filterable> = (value: V) => boolean
+export type OperatorPredicate<A extends Any> = (value: Filterable<A>) => boolean
 
-export function whereOperatorAsPredicate<
-  FTag extends string | null = string | null,
-  FKind extends string | null = string | null,
->(operator: WhereOperator<FTag, FKind>): OperatorPredicate<Filterable> {
+export function whereOperatorAsPredicate<A extends Any>(
+  operator: WhereOperator<A>,
+): OperatorPredicate<A> {
   switch (true) {
     case isParticipantOperator(operator): {
       const participant = operator.participant
@@ -97,20 +96,20 @@ export function whereOperatorAsPredicate<
       return participantIs(participant, participantPredicate)
     }
     case isTagEqual(operator): {
-      if ('eq' in operator.tag) {
-        const tag = operator.tag.eq
+      if (isString(operator.tag) || 'eq' in operator.tag) {
+        const tag = isString(operator.tag) ? operator.tag : operator.tag.eq
         return (value) => {
-          return Array.isArray(value.tags) && value.tags.includes(tag as FTag)
+          return Array.isArray(value.tags) && value.tags.includes(tag)
         }
       }
       const tag = operator.tag.neq
       return (value) => {
-        return !Array.isArray(value.tags) || !value.tags.includes(tag as FTag)
+        return !Array.isArray(value.tags) || !value.tags.includes(tag)
       }
     }
     case isKindEqual(operator): {
-      if ('eq' in operator.kind) {
-        const kind = operator.kind.eq
+      if (isString(operator.kind) || 'eq' in operator.kind) {
+        const kind = isString(operator.kind) ? operator.kind : operator.kind.eq
         return (value) => {
           return value.kind === kind
         }
@@ -137,10 +136,10 @@ export function whereOperatorAsPredicate<
   }
 }
 
-function participantIs<FTag extends string | null, FKind extends string | null>(
+function participantIs<A extends Any>(
   participant: Participant,
-  predicate: OperatorPredicate<Filterable<FTag, FKind>>,
-): OperatorPredicate<Filterable<FTag, FKind>> {
+  predicate: OperatorPredicate<A>,
+): OperatorPredicate<A> {
   return (value) => {
     if (!value.source || !value.target) {
       return false

package/src/types/scalar.ts

@@ -0,0 +1,114 @@
+import { isTruthy } from 'remeda'
+import type { Tagged } from 'type-fest'
+import { invariant } from '../utils/invariant'
+
+export type ProjectId<T = string> = Tagged<T, 'ProjectID'>
+
+export type BuiltInIcon = 'none' | `${'aws' | 'azure' | 'gcp' | 'tech'}:${string}`
+export type Icon = Tagged<string, 'Icon'> | BuiltInIcon
+export type IconUrl = Icon
+
+/**
+ * Full-qualified-name for model elements
+ *
+ * @param This - Fqn of the element (specific element)
+ * @param All - The type of all known FQNs
+ *
+ * @example
+ * ```ts
+ * type ElementAFqn = Fqn<'a', 'a' | ' | 'b'>
+ *
+ * ```
+ */
+export type Fqn<Id = string> = Tagged<Id, 'Fqn'>
+export function Fqn(name: string, parent?: Fqn | null): Fqn {
+  return (parent ? parent + '.' + name : name) as unknown as Fqn
+}
+
+export type ElementKind<Kinds = string> = Tagged<Kinds, 'ElementKind'>
+export const GroupElementKind = '@group' as ElementKind<'@group'>
+export type GroupElementKind = typeof GroupElementKind
+
+export function isGroupElementKind<V extends { kind?: any }>(v: V): v is V & { kind: GroupElementKind } {
+  return v.kind === GroupElementKind
+}
+
+/**
+ * Full-qualified-name for deployment elements
+ */
+export type DeploymentFqn<T = string> = Tagged<T, 'DeploymentFqn'>
+export function DeploymentFqn(name: string, parent?: DeploymentFqn | null): DeploymentFqn {
+  return (parent ? parent + '.' + name : name) as unknown as DeploymentFqn
+}
+
+export type DeploymentKind<Kinds = string> = Tagged<Kinds, 'DeploymentKind'>
+export type ViewId<Id = string> = Tagged<Id, 'ViewId'>
+export function ViewId(id: string): ViewId {
+  return id as any
+}
+
+export type AnyFqn<T = string> = DeploymentFqn<T> | Fqn<T>
+
+/**
+ * @deprecated Use {@link RelationshipKind} instead
+ */
+export type RelationKind<Kinds = string> = RelationshipKind<Kinds>
+
+export type RelationshipKind<Kinds = string> = Tagged<Kinds, 'RelationshipKind'>
+export type RelationId<Id = string> = Tagged<Id, 'RelationId'>
+export function RelationId(id: string): RelationId {
+  return id as any
+}
+
+export type Tag<T = string> = Tagged<T, 'Tag'>
+
+export type GlobalFqn<Id = string> = Tagged<Fqn<Id>, 'GlobalFqn'>
+export function GlobalFqn<A>(projectId: A | ProjectId<A>, name: string): GlobalFqn<A> {
+  invariant(isTruthy(projectId), 'Project ID must start with @')
+  return '@' + projectId + '.' + name as any
+}
+
+export function isGlobalFqn<A extends string>(fqn: A): fqn is GlobalFqn<A> {
+  return fqn.startsWith('@')
+}
+
+export function splitGlobalFqn<I extends string>(fqn: Fqn<I> | GlobalFqn<I>): [ProjectId | null, Fqn<I>] {
+  if (!fqn.startsWith('@')) {
+    return [null, fqn]
+  }
+  const firstDot = fqn.indexOf('.')
+  if (firstDot < 2) {
+    throw new Error('Invalid global FQN')
+  }
+  const projectId = fqn.slice(1, firstDot) as ProjectId<I>
+  const name = fqn.slice(firstDot + 1) as Fqn<I>
+  return [projectId, name]
+}
+
+export type NodeId = Tagged<string, 'NodeId' | 'Fqn' | 'DeploymentFqn'>
+export function NodeId(id: string): NodeId {
+  return id as any
+}
+export type EdgeId = Tagged<string, 'EdgeId'>
+export function EdgeId(id: string): EdgeId {
+  return id as any
+}
+
+export type StepEdgeIdLiteral = `step-${number}` | `step-${number}.${number}`
+export type StepEdgeId = Tagged<StepEdgeIdLiteral, 'EdgeId'>
+export function stepEdgeId(step: number, parallelStep?: number): StepEdgeId {
+  const id = `step-${String(step).padStart(2, '0')}` as StepEdgeId
+  return parallelStep ? `${id}.${parallelStep}` as StepEdgeId : id
+}
+export const StepEdgeKind = '@step'
+
+export function isStepEdgeId(id: string): id is StepEdgeId {
+  return id.startsWith('step-')
+}
+
+export function extractStep(id: EdgeId): number {
+  if (!isStepEdgeId(id)) {
+    throw new Error(`Invalid step edge id: ${id}`)
+  }
+  return parseFloat(id.slice('step-'.length))
+}

package/src/types/styles.ts

@@ -0,0 +1,123 @@
+import type { Tagged, TupleToUnion } from 'type-fest'
+
+/**
+ * For padding, margin, etc.
+ */
+export type SpacingSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+export type TextSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+export type ShapeSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+export const BorderStyles = ['solid', 'dashed', 'dotted', 'none'] as const
+
+export type BorderStyle = TupleToUnion<typeof BorderStyles>
+
+export const ElementShapes = [
+  'rectangle',
+  'person',
+  'browser',
+  'mobile',
+  'cylinder',
+  'storage',
+  'queue',
+] as const
+
+export type ElementShape = TupleToUnion<typeof ElementShapes>
+
+export type HexColor = `#${string}`
+
+type Comma = ',' | ', '
+export type ColorLiteral =
+  | HexColor
+  | `rgb(${number}${Comma}${number}${Comma}${number})`
+  | `rgba(${number}${Comma}${number}${Comma}${number}${Comma}${number})`
+
+export type CustomColor<T = string> = Tagged<T, 'CustomColor'>
+
+export type CustomColorDefinitions = { [key: string]: ThemeColorValues }
+
+export type RelationshipLineType = 'dashed' | 'solid' | 'dotted'
+
+// reference: https://graphviz.org/docs/attr-types/arrowType/
+export type RelationshipArrowType =
+  | 'none'
+  | 'normal'
+  | 'onormal'
+  | 'dot'
+  | 'odot'
+  | 'diamond'
+  | 'odiamond'
+  | 'crow'
+  | 'open'
+  | 'vee'
+
+export const ThemeColors = [
+  'amber',
+  'blue',
+  'gray',
+  'slate',
+  'green',
+  'indigo',
+  'muted',
+  'primary',
+  'red',
+  'secondary',
+  'sky',
+] as const
+export type ThemeColor = typeof ThemeColors[number]
+
+/**
+ * Backward compatibility alias
+ * @deprecated Use {@link ThemeColor} instead
+ */
+export type Color = ThemeColor | HexColor
+
+export function isThemeColor(color: string): color is ThemeColor {
+  return ThemeColors.includes(color as ThemeColor)
+}
+
+export interface ElementThemeColorValues {
+  fill: HexColor
+  stroke: HexColor
+  // Main text (title, etc.)
+  hiContrast: HexColor
+  // Secondary text (description, etc.)
+  loContrast: HexColor
+}
+
+export type ElementThemeColors = {
+  [key in ThemeColor]: ElementThemeColorValues
+}
+
+export interface RelationshipThemeColorValues {
+  lineColor: HexColor
+  labelBgColor: HexColor
+  labelColor: HexColor
+}
+
+export interface ThemeColorValues {
+  elements: ElementThemeColorValues
+  relationships: RelationshipThemeColorValues
+}
+
+export type RelationshipThemeColors = {
+  [key in ThemeColor]: RelationshipThemeColorValues
+}
+
+export interface LikeC4Theme {
+  font: 'Arial'
+  shadow: ColorLiteral
+  relationships: RelationshipThemeColors
+  elements: ElementThemeColors
+  sizes: {
+    [key in ShapeSize]: {
+      width: number
+      height: number
+    }
+  }
+  spacing: {
+    [key in SpacingSize]: number
+  }
+  textSizes: {
+    [key in TextSize]: number
+  }
+}