@likec4/core 1.2.0 → 1.2.1

package/src/colors/relationships.ts

@@ -0,0 +1,54 @@
+import type { RelationshipThemeColors, RelationshipThemeColorValues } from '../types/theme'
+
+const gray = {
+  lineColor: '#6E6E6E',
+  labelBgColor: '#18191b',
+  labelColor: '#C6C6C6'
+} satisfies RelationshipThemeColorValues
+const slate = {
+  lineColor: '#64748b', // 500
+  labelBgColor: '#0f172a', // 900
+  labelColor: '#cbd5e1' // 300
+} satisfies RelationshipThemeColorValues
+
+const blue = {
+  lineColor: '#3b82f6', // 500
+  labelBgColor: '#172554', // 950
+  labelColor: '#60a5fa' // 400
+} satisfies RelationshipThemeColorValues
+
+const sky = {
+  lineColor: '#0ea5e9', // 500
+  labelBgColor: '#082f49', // 950
+  labelColor: '#38bdf8' // 400
+} satisfies RelationshipThemeColorValues
+
+export const RelationshipColors = {
+  amber: {
+    lineColor: '#b45309',
+    labelBgColor: '#78350f',
+    labelColor: '#FFE0C2'
+  },
+  blue,
+  gray,
+  green: {
+    lineColor: '#15803d', // 700
+    labelBgColor: '#052e16', // 950
+    labelColor: '#22c55e' // 500
+  },
+  indigo: {
+    lineColor: '#6366f1', // 500
+    labelBgColor: '#1e1b4b', // 950
+    labelColor: '#818cf8' // 400
+  },
+  muted: slate,
+  primary: blue,
+  red: {
+    lineColor: '#AC4D39',
+    labelBgColor: '#b91c1c',
+    labelColor: '#FF977D'
+  },
+  secondary: sky,
+  sky,
+  slate
+} satisfies RelationshipThemeColors

package/src/errors/errors.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import {
+  BaseError,
+  InvalidArgError,
+  InvalidModelError,
+  invariant,
+  InvariantError,
+  NonExhaustiveError,
+  normalizeError,
+  NullableError,
+  RelationRefError,
+  UnknownError
+} from './index'
+
+describe('errors', () => {
+  describe('normalizeError', () => {
+    it.each([
+      { error: new BaseError('BaseError') },
+      { error: new RelationRefError('RelationRefError') },
+      { error: new UnknownError('UnknownError') },
+      { error: new InvariantError('InvariantError') },
+      { error: new NonExhaustiveError('NonExhaustiveError') },
+      { error: new InvalidModelError('InvalidModelError') },
+      { error: new NullableError('NullableError') },
+      { error: new InvalidArgError('InvalidArgError') }
+    ])('should return $error.name as-is', ({ error }) => {
+      expect(normalizeError(error)).toBe(error)
+    })
+
+    it.skip('should wrap an error', () => {
+      const cause = new Error('original test')
+      const error = normalizeError(cause)
+      expect(error).toBeInstanceOf(UnknownError)
+      expect(error).to.include({
+        name: 'UnknownError',
+        message: 'original test'
+      })
+      expect(error).to.have.property('cause').that.eq(cause)
+      expect(error)
+        .to.have.property('stack')
+        .that.is.a('string')
+        .and.includes('UnknownError: original test')
+    })
+
+    it('should wrap a string', () => {
+      const cause = 'error string'
+      const error = normalizeError(cause)
+      expect(error).toBeInstanceOf(UnknownError)
+      expect(error).to.include({
+        name: 'UnknownError',
+        message: cause
+      })
+      expect(error).not.to.have.property('cause')
+      expect(error).to.have.property('stack').that.is.a('string')
+    })
+
+    // Fails on serializiation of AST
+    it.skip('should wrap an object', () => {
+      const cause = { foo: 'bar' }
+      const error = normalizeError(cause)
+      expect(error).toBeInstanceOf(UnknownError)
+      expect(error).to.include({
+        name: 'UnknownError',
+        message: '{"foo":"bar"}'
+      })
+      expect(error).not.to.have.property('cause')
+      expect(error).to.have.property('stack').that.is.a('string')
+    })
+  })
+})
+
+describe('invariant', () => {
+  it('should throw an error if the condition fails', () => {
+    expect(() => invariant(false)).toThrow('Invariant failed')
+  })
+
+  it('should throw an error if the condition is null', () => {
+    expect(() => invariant(null)).toThrow(InvariantError)
+  })
+
+  it('should not throw an error if the condition passes', () => {
+    expect(() => invariant(true)).not.toThrow()
+  })
+
+  it('should throw an error with the provided message if the condition fails', () => {
+    expect(() => invariant(false, 'test')).toThrow('test')
+  })
+})

package/src/errors/index.ts

@@ -0,0 +1,120 @@
+import { CustomError } from 'ts-custom-error'
+import { isString } from '../utils/guards'
+
+export interface BaseErrorOptions {
+  cause?: unknown
+}
+
+/**
+ * Base class for all errors in the LikeC4 library.
+ */
+export class BaseError extends CustomError {
+  constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'BaseError' })
+  }
+}
+
+export class InvalidArgError extends BaseError {
+  constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'InvalidArgError' })
+  }
+}
+
+/**
+ * Unknown error, mosly probably a bug, unhandled case or coming from a third-party library.
+ */
+export class UnknownError extends BaseError {
+  constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'UnknownError' })
+  }
+}
+
+export class NullableError extends BaseError {
+  public constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'NullableError' })
+  }
+}
+
+export class InvariantError extends BaseError {
+  public constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'InvariantError' })
+  }
+}
+
+// Ensure that the value is NonNullable
+// Mostly as safer `value!`
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function nonNullable<T>(value: T, message?: string): NonNullable<T> {
+  if (typeof value === 'undefined' || value == null) {
+    throw new NullableError(message ?? `Expected defined value, but received ${value}`)
+  }
+  return value
+}
+
+export class RelationRefError extends BaseError {
+  public constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'RelationRefError' })
+  }
+}
+
+export function normalizeError(e: unknown): Error {
+  if (e instanceof BaseError || e instanceof Error) {
+    return e
+  }
+  const message = isString(e) ? e : String(e)
+  const error = new UnknownError(message)
+  try {
+    // @ts-ignore
+    Error.captureStackTrace(error, normalizeError)
+  } catch {
+    // Ignore
+  }
+  return error
+}
+
+// Throw an error if the condition fails
+// > Not providing an inline default argument for message as the result is smaller
+export function invariant(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  condition: any,
+  // Can provide a string, or a function that returns a string for cases where
+  // the message takes a fair amount of effort to compute
+  message?: string
+): asserts condition {
+  if (condition) {
+    return
+  }
+  throw new InvariantError(message ?? 'Invariant failed')
+}
+
+export class NonExhaustiveError extends BaseError {
+  public constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'NonExhaustiveError' })
+  }
+}
+
+export function nonexhaustive(value: never): never {
+  throw new NonExhaustiveError(`NonExhaustive value: ${value}`)
+}
+
+export class InvalidModelError extends BaseError {
+  public constructor(message: string, options?: BaseErrorOptions) {
+    super(message, options)
+    // Set name explicitly as minification can mangle class names
+    Object.defineProperty(this, 'name', { value: 'InvalidModelError' })
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './colors'
+export * from './errors'
+export * from './types'
+export * from './utils'
+
+// Type aliases 1
+export type * as likec4 from './types'
+// Type aliases 2
+export type * as c4 from './types'

package/src/reset.d.ts

@@ -0,0 +1,2 @@
+// Do not add any other lines of code to this file!
+import '@total-typescript/ts-reset'

package/src/types/_common.ts

@@ -0,0 +1,5 @@
+import type { Opaque } from './opaque'
+
+export type NonEmptyArray<T> = [T, ...T[]] | [...T[], T]
+
+export type IconUrl = Opaque<string, 'IconUrl'>

package/src/types/element.ts

@@ -0,0 +1,56 @@
+import type { IconUrl, NonEmptyArray } from './_common'
+import type { Opaque } from './opaque'
+import type { ThemeColor } from './theme'
+
+// Full-qualified-name
+export type Fqn = Opaque<string, 'Fqn'>
+
+export function AsFqn(name: string, parent?: Fqn | null) {
+  return (parent ? parent + '.' + name : name) as Fqn
+}
+
+export const BorderStyles = ['solid', 'dashed', 'dotted', 'none'] as const
+
+export type BorderStyle = typeof BorderStyles[number]
+
+export type ElementKind = Opaque<string, 'ElementKind'>
+export const ElementShapes = [
+  'rectangle',
+  'person',
+  'browser',
+  'mobile',
+  'cylinder',
+  'storage',
+  'queue'
+] as const
+
+export type ElementShape = typeof ElementShapes[number]
+export const DefaultThemeColor = 'primary' satisfies ThemeColor
+export const DefaultElementShape = 'rectangle' satisfies ElementShape
+
+export interface ElementStyle {
+  border?: BorderStyle
+  // 0-100
+  opacity?: number
+}
+
+export type Tag = Opaque<string, 'Tag'>
+
+export interface TagSpec {
+  readonly id: Tag
+  readonly style: ElementStyle
+}
+
+export interface Element {
+  readonly id: Fqn
+  readonly kind: ElementKind
+  readonly title: string
+  readonly description: string | null
+  readonly technology: string | null
+  readonly tags: NonEmptyArray<Tag> | null
+  readonly links: NonEmptyArray<string> | null
+  readonly icon?: IconUrl
+  readonly shape?: ElementShape
+  readonly color?: ThemeColor
+  readonly style?: ElementStyle
+}

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>
+}