@likec4/core 1.1.1 → 1.2.1

package/dist/utils/relations.spec.js

@@ -0,0 +1,210 @@
+import { describe, expect, it } from 'vitest';
+import { compareRelations, Relations } from './relations';
+const { isAnyBetween, isAnyInOut, isBetween, isIncoming, isInside, isOutgoing } = Relations;
+const relations = [
+    {
+        id: 'customer:cloud.frontend.dashboard',
+        source: 'customer',
+        target: 'cloud.frontend.dashboard',
+        title: ''
+    },
+    {
+        id: 'support:cloud.frontend.adminPanel',
+        source: 'support',
+        target: 'cloud.frontend.adminPanel',
+        title: ''
+    },
+    {
+        id: 'cloud.backend.storage:amazon.s3',
+        source: 'cloud.backend.storage',
+        target: 'amazon.s3',
+        title: ''
+    },
+    {
+        id: 'amazon.api:cloud.backend.graphql',
+        source: 'amazon.api',
+        target: 'cloud.backend.graphql',
+        title: ''
+    },
+    {
+        id: 'cloud.backend.graphql:cloud.backend.storage',
+        source: 'cloud.backend.graphql',
+        target: 'cloud.backend.storage',
+        title: ''
+    },
+    {
+        id: 'cloud.frontend.dashboard:cloud.backend.graphql',
+        source: 'cloud.frontend.dashboard',
+        target: 'cloud.backend.graphql',
+        title: ''
+    },
+    {
+        id: 'cloud.frontend.adminPanel:cloud.backend.graphql',
+        source: 'cloud.frontend.adminPanel',
+        target: 'cloud.backend.graphql',
+        title: ''
+    }
+];
+describe('relation predicates', () => {
+    const expectRelations = (predicate) => expect(relations.filter(predicate).map(r => r.id));
+    const customer = 'customer';
+    const cloud = 'cloud';
+    const frontend = 'cloud.frontend';
+    const backend = 'cloud.backend';
+    it('isBetween: cloud.frontend -> cloud.backend', () => {
+        expectRelations(isBetween(frontend, backend)).toEqual([
+            'cloud.frontend.dashboard:cloud.backend.graphql',
+            'cloud.frontend.adminPanel:cloud.backend.graphql'
+        ]);
+    });
+    it('isBetween: cloud.frontend.dashboard -> cloud.backend', () => {
+        expectRelations(isBetween('cloud.frontend.dashboard', backend)).toEqual([
+            'cloud.frontend.dashboard:cloud.backend.graphql'
+        ]);
+    });
+    it('isBetween: cloud.backend -> cloud.frontend', () => {
+        expectRelations(isBetween(backend, frontend)).toEqual([]);
+    });
+    it('isBetween: cloud.backend -> cloud.backend', () => {
+        expectRelations(isBetween(backend, backend)).toEqual([
+            'cloud.backend.graphql:cloud.backend.storage'
+        ]);
+    });
+    it('isBetween: customer -> cloud', () => {
+        expectRelations(isBetween(customer, cloud)).toEqual(['customer:cloud.frontend.dashboard']);
+    });
+    it('isIncoming: customer', () => {
+        expectRelations(isIncoming(customer)).toEqual([]);
+    });
+    it('isIncoming: cloud', () => {
+        expectRelations(isIncoming(cloud)).toEqual([
+            'customer:cloud.frontend.dashboard',
+            'support:cloud.frontend.adminPanel',
+            'amazon.api:cloud.backend.graphql'
+        ]);
+    });
+    it('isIncoming: cloud.frontend', () => {
+        expectRelations(isIncoming(frontend)).toEqual([
+            'customer:cloud.frontend.dashboard',
+            'support:cloud.frontend.adminPanel'
+        ]);
+    });
+    it('isIncoming: cloud.frontend.dashboard', () => {
+        expectRelations(isIncoming('cloud.frontend.dashboard')).toEqual([
+            'customer:cloud.frontend.dashboard'
+        ]);
+    });
+    it('isOutgoing: cloud', () => {
+        expectRelations(isOutgoing(cloud)).toEqual(['cloud.backend.storage:amazon.s3']);
+    });
+    it('isOutgoing: cloud.frontend', () => {
+        expectRelations(isOutgoing(frontend)).toEqual([
+            'cloud.frontend.dashboard:cloud.backend.graphql',
+            'cloud.frontend.adminPanel:cloud.backend.graphql'
+        ]);
+    });
+    it('isOutgoing: cloud.backend.storage', () => {
+        expectRelations(isOutgoing('cloud.backend.storage')).toEqual([
+            'cloud.backend.storage:amazon.s3'
+        ]);
+    });
+    it('isInside: cloud', () => {
+        expectRelations(isInside(cloud)).toEqual([
+            'cloud.backend.graphql:cloud.backend.storage',
+            'cloud.frontend.dashboard:cloud.backend.graphql',
+            'cloud.frontend.adminPanel:cloud.backend.graphql'
+        ]);
+    });
+    it('isInside: cloud.frontend', () => {
+        expectRelations(isInside(frontend)).toEqual([]);
+    });
+    it('isInside: cloud.backend', () => {
+        expectRelations(isInside(backend)).toEqual(['cloud.backend.graphql:cloud.backend.storage']);
+    });
+    it('isAnyInOut: customer', () => {
+        expectRelations(isAnyInOut(customer)).toEqual(['customer:cloud.frontend.dashboard']);
+    });
+    it('isAnyInOut: cloud', () => {
+        expectRelations(isAnyInOut(cloud)).toEqual([
+            'customer:cloud.frontend.dashboard',
+            'support:cloud.frontend.adminPanel',
+            'cloud.backend.storage:amazon.s3',
+            'amazon.api:cloud.backend.graphql'
+        ]);
+    });
+    it('isAnyBetween: cloud and amazon', () => {
+        expectRelations(isAnyBetween(cloud, 'amazon')).toEqual([
+            'cloud.backend.storage:amazon.s3',
+            'amazon.api:cloud.backend.graphql'
+        ]);
+    });
+});
+describe('compareRelations', () => {
+    function rel(source, target) {
+        return {
+            source,
+            target
+        };
+    }
+    function sorted(...relations) {
+        return relations.sort(compareRelations).map(r => r.source + ' -> ' + r.target);
+    }
+    it('should sort by source and target', () => {
+        expect(sorted(rel('customer', 'cloud.ui'), rel('customer', 'cloud'))).toEqual([
+            'customer -> cloud',
+            'customer -> cloud.ui'
+        ]);
+        expect(sorted(rel('1', '2.1'), rel('1', '2'), rel('1.1.1', '2'), rel('1.1.1', '2.1'), rel('1.1', '2'))).toEqual(['1 -> 2', '1 -> 2.1', '1.1 -> 2', '1.1.1 -> 2', '1.1.1 -> 2.1']);
+    });
+    it('should sort by parent', () => {
+        expect(sorted(
+        // same parent
+        rel('cloud.1.1', 'cloud.2.1'), rel('cloud.1.1', 'cloud.2'), rel('cloud.1', 'cloud.2.1'), rel('cloud.1', 'cloud.2'), 
+        // no same parent
+        rel('cloud.1.1', 'aws.1'), rel('cloud.1', 'aws.1'), rel('cloud', 'aws'))).toEqual([
+            'cloud -> aws',
+            'cloud.1 -> aws.1',
+            'cloud.1.1 -> aws.1',
+            'cloud.1 -> cloud.2',
+            'cloud.1 -> cloud.2.1',
+            'cloud.1.1 -> cloud.2',
+            'cloud.1.1 -> cloud.2.1'
+        ]);
+    });
+    it('should sort by ancestors', () => {
+        expect(sorted(
+        // same parent 2nd level
+        rel('cloud.api.1', 'cloud.api.2'), rel('cloud.ui.1', 'cloud.ui.2'), rel('cloud.ui.2', 'cloud.ui.1'), 
+        // same ancestor cloud
+        rel('cloud.ui.1', 'cloud.api.1'), rel('cloud.ui.2', 'cloud.api.2'), rel('cloud.ui', 'cloud.api.1'), 
+        // same parent 1st level
+        rel('cloud.ui', 'cloud.api'), 
+        // no same parent
+        rel('cloud.api.1', 'aws.1'), rel('cloud.api', 'aws.1'), rel('cloud.api', 'aws'), rel('cloud.ui.1', 'aws.1'), rel('cloud.ui', 'aws'), rel('cloud', 'aws'))).toEqual([
+            'cloud -> aws',
+            'cloud.api -> aws',
+            'cloud.ui -> aws',
+            'cloud.api -> aws.1',
+            'cloud.api.1 -> aws.1',
+            'cloud.ui.1 -> aws.1',
+            'cloud.ui -> cloud.api',
+            'cloud.ui -> cloud.api.1',
+            'cloud.ui.1 -> cloud.api.1',
+            'cloud.ui.2 -> cloud.api.2',
+            'cloud.api.1 -> cloud.api.2',
+            'cloud.ui.1 -> cloud.ui.2',
+            'cloud.ui.2 -> cloud.ui.1'
+        ]);
+    });
+    it('should sort relations from example', () => {
+        expect(sorted(...relations)).toEqual([
+            'customer -> cloud.frontend.dashboard',
+            'support -> cloud.frontend.adminPanel',
+            'amazon.api -> cloud.backend.graphql',
+            'cloud.backend.storage -> amazon.s3',
+            'cloud.frontend.dashboard -> cloud.backend.graphql',
+            'cloud.frontend.adminPanel -> cloud.backend.graphql',
+            'cloud.backend.graphql -> cloud.backend.storage'
+        ]);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@likec4/core",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "license": "MIT",
   "homepage": "https://likec4.dev",
   "author": "Denis Davydkov <denis@davydkov.com>",
@@ -12,15 +12,14 @@
   "bugs": "https://github.com/likec4/likec4/issues",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsc",
-    "prepack": "tsc -p tsconfig.build.json",
+    "prepack": "tsc",
     "lint": "run -T eslint src/ --fix",
     "test": "run -T vitest run",
     "clean": "run -T rimraf dist"
   },
   "files": [
     "dist",
-    "!dist/src/**",
+    "src",
     "!**/*.map"
   ],
   "type": "module",
@@ -71,10 +70,11 @@
     "type-fest": "^4.18.2"
   },
   "devDependencies": {
+    "@likec4/tsconfig": "1.2.1",
     "@total-typescript/ts-reset": "^0.5.1",
     "execa": "^9.1.0",
     "typescript": "^5.4.5",
-    "vitest": "~1.5.2"
+    "vitest": "~1.5.3"
   },
-  "packageManager": "yarn@4.2.2"
+  "packageManager": "yarn@4.3.0"
 }

package/src/colors/element.ts

@@ -0,0 +1,80 @@
+import type { ElementThemeColors, ElementThemeColorValues } from '../types/theme'
+
+const blue = {
+  fill: '#3b82f6',
+  stroke: '#2563eb',
+  hiContrast: '#eff6ff',
+  loContrast: '#bfdbfe'
+} satisfies ElementThemeColorValues
+
+const sky = {
+  fill: '#0284c7',
+  stroke: '#0369a1',
+  hiContrast: '#f0f9ff',
+  loContrast: '#B6ECF7'
+} satisfies ElementThemeColorValues
+
+const slate = {
+  fill: '#64748b',
+  stroke: '#475569',
+  hiContrast: '#f8fafc',
+  loContrast: '#cbd5e1'
+} satisfies ElementThemeColorValues
+
+export const ElementColors = {
+  primary: blue,
+  blue,
+  secondary: sky,
+  sky,
+  muted: slate,
+  slate,
+  gray: {
+    // fill: colors.neutral[500],
+    // stroke: colors.neutral[600],
+    // hiContrast: colors.neutral[50],
+    // loContrast: colors.neutral[200],
+    fill: '#737373',
+    stroke: '#525252',
+    hiContrast: '#fafafa',
+    loContrast: '#d4d4d4'
+  },
+  red: {
+    // fill: colors.red[500],
+    // stroke: colors.red[600],
+    // hiContrast: colors.red[50],
+    // loContrast: colors.red[200],
+    fill: '#AC4D39',
+    // fill: '#b54548',
+    stroke: '#853A2D',
+    // hiContrast: '#fef2f2',
+    // loContrast: '#fecaca',
+    // hiContrast: '#191111', // colors.gray[900],
+    // loContrast: '#3b1219' // colors.gray[800],
+    hiContrast: '#FBD3CB',
+    // hiContrast: '#f8fafc',
+    // loContrast: '#fdd8d8' // radix black red 12
+    loContrast: '#FF977D'
+  },
+  green: {
+    fill: '#428a4f',
+    stroke: '#2d5d39',
+    hiContrast: '#f8fafc',
+    loContrast: '#c2f0c2'
+  },
+  amber: {
+    fill: '#A35829',
+    stroke: '#7E451D',
+    hiContrast: '#FFE0C2',
+    loContrast: '#FFA057'
+  },
+  indigo: {
+    // fill: colors.indigo[500],
+    // stroke: colors.indigo[600],
+    // hiContrast: colors.indigo[50],
+    // loContrast: colors.indigo[200],
+    fill: '#6366f1',
+    stroke: '#4f46e5',
+    hiContrast: '#eef2ff',
+    loContrast: '#c7d2fe'
+  }
+} as const satisfies ElementThemeColors

package/src/colors/index.ts

@@ -0,0 +1,12 @@
+import type { LikeC4Theme } from '../types/theme'
+import { ElementColors } from './element'
+import { RelationshipColors } from './relationships'
+
+export const defaultTheme = {
+  elements: ElementColors,
+  relationships: RelationshipColors,
+  font: 'Helvetica',
+  shadow: '#0a0a0a'
+} satisfies LikeC4Theme
+
+export { ElementColors, RelationshipColors }

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