@likec4/core 1.1.1 → 1.2.1

package/src/types/expression.ts

@@ -0,0 +1,140 @@
+import type { IconUrl } from './_common'
+import type { BorderStyle, ElementKind, ElementShape, Fqn, Tag } from './element'
+import type { ThemeColor } from './theme'
+import type { ViewID } from './view'
+
+interface BaseExpr {
+  element?: never
+  custom?: never
+  expanded?: never
+  elementKind?: never
+  elementTag?: never
+  isEqual?: never
+  isDescedants?: never
+  wildcard?: never
+  source?: never
+  target?: never
+  inout?: never
+  incoming?: never
+  outgoing?: never
+}
+
+export interface ElementRefExpr extends Omit<BaseExpr, 'element' | 'isDescedants'> {
+  element: Fqn
+  isDescedants?: boolean
+}
+export function isElementRef(expr: Expression): expr is ElementRefExpr {
+  return 'element' in expr
+}
+
+export interface ExpandedElementExpr extends Omit<BaseExpr, 'expanded'> {
+  expanded: Fqn
+}
+export function isExpandedElementExpr(expr: Expression): expr is ExpandedElementExpr {
+  return 'expanded' in expr
+}
+
+export interface CustomElementExpr extends Omit<BaseExpr, 'custom'> {
+  custom: {
+    element: Fqn
+    title?: string
+    description?: string
+    technology?: string
+    shape?: ElementShape
+    color?: ThemeColor
+    icon?: IconUrl
+    border?: BorderStyle
+    opacity?: number
+    navigateTo?: ViewID
+  }
+}
+
+export function isCustomElement(expr: Expression): expr is CustomElementExpr {
+  return 'custom' in expr
+}
+
+export interface WildcardExpr extends Omit<BaseExpr, 'wildcard'> {
+  wildcard: true
+}
+export function isWildcard(expr: Expression): expr is WildcardExpr {
+  return 'wildcard' in expr
+}
+export interface ElementKindExpr extends Omit<BaseExpr, 'elementKind' | 'isEqual'> {
+  elementKind: ElementKind
+  isEqual: boolean
+}
+export function isElementKindExpr(expr: Expression): expr is ElementKindExpr {
+  return 'elementKind' in expr && 'isEqual' in expr
+}
+
+export interface ElementTagExpr extends Omit<BaseExpr, 'elementTag' | 'isEqual'> {
+  elementTag: Tag
+  isEqual: boolean
+}
+export function isElementTagExpr(expr: Expression): expr is ElementTagExpr {
+  return 'elementTag' in expr && 'isEqual' in expr
+}
+
+export type ElementExpression =
+  | ElementRefExpr
+  | WildcardExpr
+  | ElementKindExpr
+  | ElementTagExpr
+  | ExpandedElementExpr
+export function isElement(expr: Expression): expr is ElementExpression {
+  return isElementRef(expr)
+    || isWildcard(expr)
+    || isElementKindExpr(expr)
+    || isElementTagExpr(expr)
+    || isExpandedElementExpr(expr)
+}
+
+export interface RelationExpr extends Omit<BaseExpr, 'source' | 'target'> {
+  source: ElementExpression
+  target: ElementExpression
+  isBidirectional?: boolean
+}
+export function isRelation(expr: Expression): expr is RelationExpr {
+  return 'source' in expr && 'target' in expr
+}
+
+export interface InOutExpr extends Omit<BaseExpr, 'inout'> {
+  inout: ElementExpression
+}
+export function isInOut(expr: Expression): expr is InOutExpr {
+  return 'inout' in expr
+}
+
+export interface IncomingExpr extends Omit<BaseExpr, 'incoming'> {
+  incoming: ElementExpression
+}
+export function isIncoming(expr: Expression): expr is IncomingExpr {
+  return 'incoming' in expr
+}
+export interface OutgoingExpr extends Omit<BaseExpr, 'outgoing'> {
+  outgoing: ElementExpression
+}
+export function isOutgoing(expr: Expression): expr is OutgoingExpr {
+  return 'outgoing' in expr
+}
+
+export type AnyRelationExpression = RelationExpr | InOutExpr | IncomingExpr | OutgoingExpr
+
+export function isAnyRelation(expr: Expression): expr is AnyRelationExpression {
+  return isRelation(expr) || isInOut(expr) || isIncoming(expr) || isOutgoing(expr)
+}
+
+export type Expression = ElementExpression | CustomElementExpr | AnyRelationExpression
+
+// export const Expr = {
+//   isElementRef,
+//   isWildcard,
+//   isElementKindExpr,
+//   isElementTagExpr,
+//   isElement,
+//   isRelation,
+//   isInOut,
+//   isIncoming,
+//   isOutgoing,
+//   isAnyRelation,
+// }

package/src/types/index.ts

@@ -0,0 +1,10 @@
+export * from './_common'
+export * from './element'
+export * from './expression'
+export * from './model'
+export * from './opaque'
+export * from './relation'
+export * from './theme'
+export * from './view'
+
+export * as Expr from './expression'

package/src/types/model.ts

@@ -0,0 +1,15 @@
+import type { Element, Fqn } from './element'
+import type { Relation, RelationID } from './relation'
+import type { ComputedView, View, ViewID } from './view'
+
+export interface LikeC4Model {
+  elements: Record<Fqn, Element>
+  relations: Record<RelationID, Relation>
+  views: Record<ViewID, View>
+}
+
+export interface LikeC4ComputedModel {
+  elements: Record<Fqn, Element>
+  relations: Record<RelationID, Relation>
+  views: Record<ViewID, ComputedView>
+}

package/src/types/opaque.ts

@@ -0,0 +1,108 @@
+declare const tag: unique symbol
+
+type Tagged<Token> = {
+  readonly [tag]: Token
+}
+
+/**
+Create an opaque type, which hides its internal details from the public, and can only be created by being used explicitly.
+
+The generic type parameter can be anything. It doesn't have to be an object.
+
+[Read more about opaque types.](https://codemix.com/opaque-types-in-javascript/)
+
+There have been several discussions about adding this feature to TypeScript via the `opaque type` operator, similar to how Flow does it. Unfortunately, nothing has (yet) moved forward:
+	- [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
+	- [Microsoft/TypeScript#15408](https://github.com/Microsoft/TypeScript/issues/15408)
+	- [Microsoft/TypeScript#15807](https://github.com/Microsoft/TypeScript/issues/15807)
+
+@example
+```
+import type {Opaque} from 'type-fest';
+
+type AccountNumber = Opaque<number, 'AccountNumber'>;
+type AccountBalance = Opaque<number, 'AccountBalance'>;
+
+// The `Token` parameter allows the compiler to differentiate between types, whereas "unknown" will not. For example, consider the following structures:
+type ThingOne = Opaque<string>;
+type ThingTwo = Opaque<string>;
+
+// To the compiler, these types are allowed to be cast to each other as they have the same underlying type. They are both `string & { __opaque__: unknown }`.
+// To avoid this behaviour, you would instead pass the "Token" parameter, like so.
+type NewThingOne = Opaque<string, 'ThingOne'>;
+type NewThingTwo = Opaque<string, 'ThingTwo'>;
+
+// Now they're completely separate types, so the following will fail to compile.
+function createNewThingOne (): NewThingOne {
+	// As you can see, casting from a string is still allowed. However, you may not cast NewThingOne to NewThingTwo, and vice versa.
+	return 'new thing one' as NewThingOne;
+}
+
+// This will fail to compile, as they are fundamentally different types.
+const thingTwo = createNewThingOne() as NewThingTwo;
+
+// Here's another example of opaque typing.
+function createAccountNumber(): AccountNumber {
+	return 2 as AccountNumber;
+}
+
+function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance {
+	return 4 as AccountBalance;
+}
+
+// This will compile successfully.
+getMoneyForAccount(createAccountNumber());
+
+// But this won't, because it has to be explicitly passed as an `AccountNumber` type.
+getMoneyForAccount(2);
+
+// You can use opaque values like they aren't opaque too.
+const accountNumber = createAccountNumber();
+
+// This will not compile successfully.
+const newAccountNumber = accountNumber + 2;
+
+// As a side note, you can (and should) use recursive types for your opaque types to make them stronger and hopefully easier to type.
+type Person = {
+	id: Opaque<number, Person>;
+	name: string;
+};
+```
+
+@category Type
+*/
+export type Opaque<Type, Token = unknown> = Type & Tagged<Token>
+
+/**
+Revert an opaque type back to its original type by removing the readonly `[tag]`.
+
+Why is this necessary?
+
+1. Use an `Opaque` type as object keys
+2. Prevent TS4058 error: "Return type of exported function has or is using name X from external module Y but cannot be named"
+
+@example
+```
+import type {Opaque, UnwrapOpaque} from 'type-fest';
+
+type AccountType = Opaque<'SAVINGS' | 'CHECKING', 'AccountType'>;
+
+const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
+	SAVINGS: 99,
+	CHECKING: 0.1
+};
+
+// Without UnwrapOpaque, the following expression would throw a type error.
+const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
+
+// Attempting to pass an non-Opaque type to UnwrapOpaque will raise a type error.
+type WontWork = UnwrapOpaque<string>;
+```
+
+@category Type
+*/
+export type UnwrapOpaque<OpaqueType extends Tagged<unknown>> = OpaqueType extends Opaque<
+  infer Type,
+  OpaqueType[typeof tag]
+> ? Type
+  : OpaqueType

package/src/types/relation.ts

@@ -0,0 +1,38 @@
+import type { NonEmptyArray } from './_common'
+import type { Fqn, Tag } from './element'
+import type { Opaque } from './opaque'
+import type { ThemeColor } from './theme'
+
+export type RelationID = Opaque<string, 'RelationID'>
+export type RelationshipKind = Opaque<string, 'RelationshipKind'>
+
+export type RelationshipLineType = 'dashed' | 'solid' | 'dotted'
+
+// reference: https://graphviz.org/docs/attr-types/arrowType/
+export type RelationshipArrowType =
+  | 'none'
+  | 'normal'
+  | 'onormal'
+  | 'diamond'
+  | 'odiamond'
+  | 'crow'
+  | 'open'
+  | 'vee'
+
+export const DefaultLineStyle = 'dashed' satisfies RelationshipLineType
+export const DefaultArrowType = 'normal' satisfies RelationshipArrowType
+export const DefaultRelationshipColor = 'gray' satisfies ThemeColor
+
+export interface Relation {
+  readonly id: RelationID
+  readonly source: Fqn
+  readonly target: Fqn
+  readonly title: string
+  readonly tags?: NonEmptyArray<Tag>
+  readonly kind?: RelationshipKind
+  readonly color?: ThemeColor
+  readonly line?: RelationshipLineType
+  readonly head?: RelationshipArrowType
+  readonly tail?: RelationshipArrowType
+  readonly links?: NonEmptyArray<string>
+}

package/src/types/theme.ts

@@ -0,0 +1,46 @@
+export type ThemeColor =
+  | 'amber'
+  | 'blue'
+  | 'gray'
+  | 'slate'
+  | 'green'
+  | 'indigo'
+  | 'muted'
+  | 'primary'
+  | 'red'
+  | 'secondary'
+  | 'sky'
+
+export type HexColorLiteral = `#${string}`
+
+export type ColorLiteral = HexColorLiteral
+
+export interface ElementThemeColorValues {
+  fill: ColorLiteral
+  stroke: ColorLiteral
+  // Main text (title, etc.)
+  hiContrast: ColorLiteral
+  // Secondary text (description, etc.)
+  loContrast: ColorLiteral
+}
+
+export type ElementThemeColors = {
+  [key in ThemeColor]: ElementThemeColorValues
+}
+
+export interface RelationshipThemeColorValues {
+  lineColor: ColorLiteral
+  labelBgColor: ColorLiteral
+  labelColor: ColorLiteral
+}
+
+export type RelationshipThemeColors = {
+  [key in ThemeColor]: RelationshipThemeColorValues
+}
+
+export interface LikeC4Theme {
+  font: 'Helvetica' // for now only support Helvetica
+  shadow: ColorLiteral
+  relationships: RelationshipThemeColors
+  elements: ElementThemeColors
+}

package/src/types/view.ts

@@ -0,0 +1,263 @@
+import { isNullish } from 'remeda'
+import type { IconUrl, NonEmptyArray } from './_common'
+import type { ElementKind, ElementShape, ElementStyle, Fqn, Tag } from './element'
+import type { CustomElementExpr, ElementExpression, Expression } from './expression'
+import type { Opaque } from './opaque'
+import type { RelationID, RelationshipArrowType, RelationshipLineType } from './relation'
+import type { ColorLiteral, ThemeColor } from './theme'
+
+// Full-qualified-name
+export type ViewID = Opaque<string, 'ViewID'>
+
+export type ViewRuleExpression =
+  | {
+    include: Expression[]
+    exclude?: never
+  }
+  | {
+    include?: never
+    exclude: Expression[]
+  }
+export function isViewRuleExpression(rule: ViewRule): rule is ViewRuleExpression {
+  return (
+    ('include' in rule && Array.isArray(rule.include))
+    || ('exclude' in rule && Array.isArray(rule.exclude))
+  )
+}
+
+export interface ViewRuleStyle {
+  targets: ElementExpression[]
+  style: ElementStyle & {
+    color?: ThemeColor
+    shape?: ElementShape
+    icon?: IconUrl
+  }
+}
+export function isViewRuleStyle(rule: ViewRule): rule is ViewRuleStyle {
+  return 'style' in rule && 'targets' in rule
+}
+
+export type AutoLayoutDirection = 'TB' | 'BT' | 'LR' | 'RL'
+export interface ViewRuleAutoLayout {
+  autoLayout: AutoLayoutDirection
+}
+export function isViewRuleAutoLayout(rule: ViewRule): rule is ViewRuleAutoLayout {
+  return 'autoLayout' in rule
+}
+
+export type ViewRule = ViewRuleExpression | ViewRuleStyle | ViewRuleAutoLayout
+
+export interface BasicView<ViewType extends 'element' | 'dynamic' = 'element' | 'dynamic'> {
+  readonly __?: ViewType
+  readonly id: ViewID
+  readonly title: string | null
+  readonly description: string | null
+  readonly tags: NonEmptyArray<Tag> | null
+  readonly links: NonEmptyArray<string> | null
+
+  /**
+   * URI to the source file of this view.
+   * Undefined if the view is auto-generated.
+   */
+  readonly docUri?: string
+  /**
+   * For all views we find common ancestor path.
+   * This is used to generate relative paths, i.e.:
+   * - "" for views in the common ancestor directory (or root)
+   * - "subdir" for views in "<root>/subdir"
+   * - "subdir/subdir1" for views in "<root>/subdir/subdir1"
+   *
+   * Undefined if the view is auto-generated.
+   */
+  readonly relativePath?: string
+}
+
+export interface BasicElementView extends BasicView<'element'> {
+  readonly viewOf?: Fqn
+  readonly rules: ViewRule[]
+}
+export interface StrictElementView extends BasicElementView {
+  readonly viewOf: Fqn
+}
+
+export interface ExtendsElementView extends BasicElementView {
+  readonly extends: ViewID
+}
+export type ElementView = StrictElementView | ExtendsElementView | BasicElementView
+
+export interface DynamicViewStep {
+  readonly source: Fqn
+  readonly target: Fqn
+  readonly title: string | null
+  readonly isBackward?: boolean
+}
+
+export type DynamicViewIncludeRule = {
+  include: (ElementExpression | CustomElementExpr)[]
+}
+
+export function isDynamicViewIncludeRule(rule: DynamicViewRule): rule is DynamicViewIncludeRule {
+  return 'include' in rule && Array.isArray(rule.include)
+}
+
+export type DynamicViewRule = DynamicViewIncludeRule | ViewRuleStyle | ViewRuleAutoLayout
+export interface DynamicView extends BasicView<'dynamic'> {
+  readonly __: 'dynamic'
+
+  readonly steps: DynamicViewStep[]
+
+  readonly rules: DynamicViewRule[]
+}
+
+export type View = ElementView | DynamicView
+
+export function isDynamicView(view: View): view is DynamicView {
+  return view.__ === 'dynamic'
+}
+export function isElementView(view: View): view is ElementView {
+  return isNullish(view.__) || view.__ === 'element'
+}
+
+export function isExtendsElementView(view: View): view is ExtendsElementView {
+  return isElementView(view) && 'extends' in view
+}
+
+export function isStrictElementView(view: View): view is StrictElementView {
+  return isElementView(view) && 'viewOf' in view
+}
+
+export type NodeId = Fqn
+
+export type EdgeId = Opaque<string, 'EdgeId'>
+
+export type StepEdgeIdLiteral = `step-${number}`
+export type StepEdgeId = Opaque<StepEdgeIdLiteral, 'EdgeId'>
+export function StepEdgeId(step: number): StepEdgeId {
+  return `step-${String(step).padStart(3, '0')}` as StepEdgeId
+}
+
+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 Number(id.slice('step-'.length))
+}
+
+export interface ComputedNode {
+  id: NodeId
+  kind: ElementKind
+  parent: NodeId | null
+  title: string
+  description: string | null
+  technology: string | null
+  tags: NonEmptyArray<Tag> | null
+  links: NonEmptyArray<string> | null
+  children: NodeId[]
+  inEdges: EdgeId[]
+  outEdges: EdgeId[]
+  shape: ElementShape
+  /**
+   * @deprecated Use `style` instead
+   */
+  color: ThemeColor
+  /**
+   * @deprecated Use `style` instead
+   */
+  icon?: IconUrl
+  style: ElementStyle
+  navigateTo?: ViewID
+  level: number
+  // For compound nodes, the max depth of nested nodes
+  depth?: number
+}
+
+export interface ComputedEdge {
+  id: EdgeId
+  parent: NodeId | null
+  source: NodeId
+  target: NodeId
+  label: string | null
+  relations: RelationID[]
+  color?: ThemeColor
+  line?: RelationshipLineType
+  head?: RelationshipArrowType
+  tail?: RelationshipArrowType
+
+  /**
+   * For layouting purposes
+   * @default 'forward'
+   */
+  dir?: 'forward' | 'back'
+}
+
+export interface ComputedElementView extends Omit<ElementView, 'rules'> {
+  readonly extends?: ViewID
+  readonly autoLayout: ViewRuleAutoLayout['autoLayout']
+  readonly nodes: ComputedNode[]
+  readonly edges: ComputedEdge[]
+}
+export interface ComputedDynamicView extends Omit<DynamicView, 'rules' | 'steps'> {
+  readonly autoLayout: ViewRuleAutoLayout['autoLayout']
+  readonly nodes: ComputedNode[]
+  readonly edges: ComputedEdge[]
+}
+export function isComputedDynamicView(view: ComputedView): view is ComputedDynamicView {
+  return view.__ === 'dynamic'
+}
+
+export type ComputedView = ComputedElementView | ComputedDynamicView
+
+export function isComputedElementView(view: ComputedView): view is ComputedElementView {
+  return isNullish(view.__) || view.__ === 'element'
+}
+
+export type Point = readonly [x: number, y: number]
+
+// Bounding box
+export type BBox = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface DiagramLabel {
+  align: 'left' | 'right' | 'center'
+  fontStyle?: 'bold' | 'normal'
+  color?: ColorLiteral
+  fontSize: number
+  pt: Point
+  width: number
+  text: string
+}
+
+export interface DiagramNode extends ComputedNode {
+  width: number
+  height: number
+  position: Point // Absolute position, top left
+  // relative: Point // Top left, relative to parent
+  labels: DiagramLabel[]
+}
+
+export interface DiagramEdge extends ComputedEdge {
+  points: NonEmptyArray<Point>
+  // Polygons are used to draw arrows
+  headArrow?: NonEmptyArray<Point>
+  // Draw arrow from the last point of the edge to this point
+  headArrowPoint?: Point
+  tailArrow?: NonEmptyArray<Point>
+  // Draw arrow from the first point of the edge to this point
+  tailArrowPoint?: Point
+  labels?: NonEmptyArray<DiagramLabel>
+  labelBBox?: BBox
+}
+
+export interface DiagramView extends Omit<ComputedView, 'nodes' | 'edges'> {
+  readonly nodes: DiagramNode[]
+  readonly edges: DiagramEdge[]
+  readonly width: number
+  readonly height: number
+}