@likec4/core 1.31.0 → 1.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@likec4/core",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "license": "MIT",
   "homepage": "https://likec4.dev",
   "author": "Denis Davydkov <denis@davydkov.com>",
@@ -69,6 +69,14 @@
         "default": "./dist/utils/index.mjs"
       }
     },
+    "./types/aux": {
+      "sources": "./src/types/aux.ts",
+      "default": {
+        "types": "./dist/types/aux.d.mts",
+        "import": "./dist/types/aux.mjs",
+        "default": "./dist/types/aux.mjs"
+      }
+    },
     "./types": {
       "sources": "./src/types/index.ts",
       "default": {
@@ -85,11 +93,11 @@
     "access": "public"
   },
   "dependencies": {
-    "type-fest": "^4.40.0"
+    "type-fest": "^4.41.0"
   },
   "devDependencies": {
     "@dagrejs/dagre": "1.1.4",
-    "@mantine/colors-generator": "8.0.1",
+    "@mantine/colors-generator": "8.1.0",
     "@types/natural-compare-lite": "^1.4.2",
     "@types/object-hash": "^3.0.6",
     "chroma-js": "^3.1.2",
@@ -102,12 +110,12 @@
     "natural-compare-lite": "^1.4.0",
     "object-hash": "^3.0.0",
     "obliterator": "^2.0.5",
-    "remeda": "^2.21.3",
-    "turbo": "^2.5.2",
+    "remeda": "^2.23.0",
+    "turbo": "^2.5.4",
     "typescript": "^5.8.3",
     "unbuild": "^3.5.0",
-    "vitest": "^3.1.2",
-    "@likec4/tsconfig": "1.31.0"
+    "vitest": "3.2.3",
+    "@likec4/tsconfig": "1.32.1"
   },
   "scripts": {
     "typecheck": "tsc -b --verbose",
@@ -115,7 +123,7 @@
     "lint": "run -T eslint src/ --fix",
     "test": "vitest run --no-isolate",
     "test:watch": "vitest",
-    "clean": "rm -r -f dist",
+    "clean": "pnpm rimraf dist lib",
     "pack": "pnpm pack"
   }
 }

package/src/builder/Builder.deploymentModel.ts

@@ -1,16 +1,16 @@
 import type { LastArrayElement, Split } from 'type-fest'
-import type { DeploymentElement, DeploymentRelation, Fqn } from '../types'
+import type { DeploymentElement, DeploymentFqn, DeploymentRelationship } from '../types'
 import type { AnyTypes, Invalid, Types, ValidId } from './_types'
 import type { Builder } from './Builder'
 import type { AddDeploymentNode } from './Builder.deployment'
 
 export interface DeploymentModelBuilder<T extends AnyTypes> extends Builder<T> {
   __addDeployment(node: DeploymentElement): Builder<T>
-  __addDeploymentRelation(rel: Omit<DeploymentRelation, 'id'>): Builder<T>
+  __addDeploymentRelation(rel: Omit<DeploymentRelationship, 'id'>): Builder<T>
   /**
    * Create a fully qualified name from an id (for nested models)
    */
-  __fqn(id: string): Fqn
+  __deploymentFqn(id: string): DeploymentFqn
 }
 
 export function deployment<A extends AnyTypes>(): (input: Builder<A>) => Builder<A>
@@ -328,7 +328,23 @@ export function deployment(...ops: any[]) {
 type NameFromFqn<FQN extends string> = LastArrayElement<Split<FQN, '.'>>
 
 export type AddDeployedInstance<Props = unknown> = {
-  //  instanceOf(target, titleOrProps?)
+  /**
+   * @example
+   * ```ts
+   * builder.deployment(({ node, instanceOf }, _) =>
+   *    _(
+   *      node('node1').with(
+   *        // Only FQN of the element
+   *        instanceOf('cloud.backend'),
+   *        // ID, FQN of the element and additional props
+   *        instanceOf('b2', 'cloud.backend', {
+   *          tags: ['tag2'],
+   *        }),
+   *      ),
+   *    )
+   *  )
+   * ```
+   */
   <
     const T extends AnyTypes,
     Id extends string & T['Fqn'],
@@ -336,7 +352,23 @@ export type AddDeployedInstance<Props = unknown> = {
     target: Id,
   ): (builder: DeploymentModelBuilder<T>) => DeploymentModelBuilder<Types.AddDeploymentFqn<T, NameFromFqn<Id>>>
 
-  //  instanceOf(id, target, titleOrProps?)
+  /**
+   * @example
+   * ```ts
+   * builder.deployment(({ node, instanceOf }, _) =>
+   *    _(
+   *      node('node1').with(
+   *        // Only FQN of the element
+   *        instanceOf('cloud.backend'),
+   *        // ID, FQN of the element and additional props
+   *        instanceOf('b2', 'cloud.backend', {
+   *          tags: ['tag2'],
+   *        }),
+   *      ),
+   *    )
+   *  )
+   * ```
+   */
   <
     const Id extends string,
     T extends AnyTypes,
@@ -348,10 +380,32 @@ export type AddDeployedInstance<Props = unknown> = {
   ): (builder: DeploymentModelBuilder<T>) => DeploymentModelBuilder<Types.AddDeploymentFqn<T, Id>>
 }
 
-type AddDeploymentNodeHelper<T = unknown> = <const Id extends string>(
-  id: ValidId<Id>,
-  titleOrProps?: string | T,
-) => AddDeploymentNode<Id>
+type AddDeploymentNodeHelper<T = unknown> =
+  /**
+   * Adds deployment model
+   *
+   * @example
+   *  builder.deployment(({ node }, _) =>
+   *    _(
+   *      node('node1').with(
+   *        node('child1')
+   *      ),
+   *    )
+   *  )
+   *
+   * @example
+   *  builder.deployment((_,d) =>
+   *    d(
+   *      _.node('node1').with(
+   *        _.node('child1')
+   *      ),
+   *    )
+   *  )
+   */
+  <const Id extends string>(
+    id: ValidId<Id>,
+    titleOrProps?: string | T,
+  ) => AddDeploymentNode<Id>
 
 export type AddDeploymentNodeHelpers<T extends AnyTypes> = T extends
   Types<any, any, any, any, any, any, infer Kinds extends string, any> ? {
@@ -359,15 +413,25 @@ export type AddDeploymentNodeHelpers<T extends AnyTypes> = T extends
   }
   : Invalid<'No Deployment Kinds'>
 
-export type AddDeploymentRelation<Props = unknown> = <
-  T extends AnyTypes,
-  Source extends string & T['DeploymentFqn'],
-  Target extends string & T['DeploymentFqn'],
->(
-  source: Source,
-  target: Target,
-  titleOrProps?: string | Props,
-) => (builder: DeploymentModelBuilder<T>) => DeploymentModelBuilder<T>
+export type AddDeploymentRelation<Props = unknown> =
+  /**
+   * @example
+   * ```ts
+   * rel('source.deployment', 'target.deployment', {
+   *   title: 'title',
+   *   tags: ['tag1'],
+   * })
+   * ```
+   */
+  <
+    T extends AnyTypes,
+    Source extends string & T['DeploymentFqn'],
+    Target extends string & T['DeploymentFqn'],
+  >(
+    source: Source,
+    target: Target,
+    titleOrProps?: string | Props,
+  ) => (builder: DeploymentModelBuilder<T>) => DeploymentModelBuilder<T>
 
 export type DeloymentModelHelpers<T extends AnyTypes> = AddDeploymentNodeHelpers<T> & {
   instanceOf: AddDeployedInstance<T['NewDeploymentNodeProps']>

package/src/builder/Builder.element.ts

@@ -55,35 +55,55 @@ type FromNested<T extends AnyTypes, N> = N extends TypesNested<any, any, infer F
  * Chainable builder to create element
  */
 export interface AddElement<Id extends string> {
+  /**
+   * @example
+   * ```ts
+   * el('a')
+   * ```
+   */
   <T extends AnyTypes>(builder: ModelBuilder<T>): ModelBuilder<Types.AddFqn<T, Id>>
 
+  /**
+   * @example
+   * ```ts
+   * el('a').with()
+   * ```
+   */
   with<T extends AnyTypes>(): (builder: ModelBuilder<T>) => ModelBuilder<Types.AddFqn<T, Id>>
 
+  /**
+   * @example
+   * ```ts
+   * el('a').with(
+   *   relTo('b')
+   * )
+   * ```
+   */
   with<
     T extends AnyTypes,
-    A extends AnyTypes
+    A extends AnyTypes,
   >(
-    op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>
+    op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, A>>
 
   with<
     T extends AnyTypes,
     A extends AnyTypes,
-    B extends AnyTypes
+    B extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
-    op2: (input: ModelBuilder<A>) => ModelBuilder<B>
+    op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, B>>
 
   with<
     T extends AnyTypes,
     A extends AnyTypes,
     B extends AnyTypes,
-    C extends AnyTypes
+    C extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
-    op3: (input: ModelBuilder<B>) => ModelBuilder<C>
+    op3: (input: ModelBuilder<B>) => ModelBuilder<C>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, C>>
 
   with<
@@ -91,12 +111,12 @@ export interface AddElement<Id extends string> {
     A extends AnyTypes,
     B extends AnyTypes,
     C extends AnyTypes,
-    D extends AnyTypes
+    D extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
     op3: (input: ModelBuilder<B>) => ModelBuilder<C>,
-    op4: (input: ModelBuilder<C>) => ModelBuilder<D>
+    op4: (input: ModelBuilder<C>) => ModelBuilder<D>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, D>>
 
   with<
@@ -105,13 +125,13 @@ export interface AddElement<Id extends string> {
     B extends AnyTypes,
     C extends AnyTypes,
     D extends AnyTypes,
-    E extends AnyTypes
+    E extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
     op3: (input: ModelBuilder<B>) => ModelBuilder<C>,
     op4: (input: ModelBuilder<C>) => ModelBuilder<D>,
-    op5: (input: ModelBuilder<D>) => ModelBuilder<E>
+    op5: (input: ModelBuilder<D>) => ModelBuilder<E>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, E>>
 
   with<
@@ -121,14 +141,14 @@ export interface AddElement<Id extends string> {
     C extends AnyTypes,
     D extends AnyTypes,
     E extends AnyTypes,
-    F extends AnyTypes
+    F extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
     op3: (input: ModelBuilder<B>) => ModelBuilder<C>,
     op4: (input: ModelBuilder<C>) => ModelBuilder<D>,
     op5: (input: ModelBuilder<D>) => ModelBuilder<E>,
-    op6: (input: ModelBuilder<E>) => ModelBuilder<F>
+    op6: (input: ModelBuilder<E>) => ModelBuilder<F>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, F>>
 
   with<
@@ -139,7 +159,7 @@ export interface AddElement<Id extends string> {
     D extends AnyTypes,
     E extends AnyTypes,
     F extends AnyTypes,
-    G extends AnyTypes
+    G extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
@@ -147,7 +167,7 @@ export interface AddElement<Id extends string> {
     op4: (input: ModelBuilder<C>) => ModelBuilder<D>,
     op5: (input: ModelBuilder<D>) => ModelBuilder<E>,
     op6: (input: ModelBuilder<E>) => ModelBuilder<F>,
-    op7: (input: ModelBuilder<F>) => ModelBuilder<G>
+    op7: (input: ModelBuilder<F>) => ModelBuilder<G>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, G>>
 
   with<
@@ -159,7 +179,7 @@ export interface AddElement<Id extends string> {
     E extends AnyTypes,
     F extends AnyTypes,
     G extends AnyTypes,
-    H extends AnyTypes
+    H extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
@@ -168,7 +188,7 @@ export interface AddElement<Id extends string> {
     op5: (input: ModelBuilder<D>) => ModelBuilder<E>,
     op6: (input: ModelBuilder<E>) => ModelBuilder<F>,
     op7: (input: ModelBuilder<F>) => ModelBuilder<G>,
-    op8: (input: ModelBuilder<G>) => ModelBuilder<H>
+    op8: (input: ModelBuilder<G>) => ModelBuilder<H>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, H>>
 
   with<
@@ -181,7 +201,7 @@ export interface AddElement<Id extends string> {
     F extends AnyTypes,
     G extends AnyTypes,
     H extends AnyTypes,
-    I extends AnyTypes
+    I extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
@@ -191,7 +211,7 @@ export interface AddElement<Id extends string> {
     op6: (input: ModelBuilder<E>) => ModelBuilder<F>,
     op7: (input: ModelBuilder<F>) => ModelBuilder<G>,
     op8: (input: ModelBuilder<G>) => ModelBuilder<H>,
-    op9: (input: ModelBuilder<H>) => ModelBuilder<I>
+    op9: (input: ModelBuilder<H>) => ModelBuilder<I>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, I>>
 
   with<
@@ -205,7 +225,7 @@ export interface AddElement<Id extends string> {
     G extends AnyTypes,
     H extends AnyTypes,
     I extends AnyTypes,
-    J extends AnyTypes
+    J extends AnyTypes,
   >(
     op1: (input: ModelBuilder<ToNested<T, Id>>) => ModelBuilder<A>,
     op2: (input: ModelBuilder<A>) => ModelBuilder<B>,
@@ -216,6 +236,6 @@ export interface AddElement<Id extends string> {
     op7: (input: ModelBuilder<F>) => ModelBuilder<G>,
     op8: (input: ModelBuilder<G>) => ModelBuilder<H>,
     op9: (input: ModelBuilder<H>) => ModelBuilder<I>,
-    op10: (input: ModelBuilder<I>) => ModelBuilder<J>
+    op10: (input: ModelBuilder<I>) => ModelBuilder<J>,
   ): (builder: ModelBuilder<T>) => ModelBuilder<FromNested<T, J>>
 }

package/src/builder/Builder.model.ts

@@ -403,25 +403,74 @@ export function model(...ops: any[]) {
   }
 }
 
-export type RelationshipHelper<Props = unknown> = <
-  T extends AnyTypes,
-  From extends string & T['Fqn'],
-  To extends string & T['Fqn'],
->(
-  from: From,
-  to: To,
-  titleOrProps?: string | Props,
-) => (builder: ModelBuilder<T>) => ModelBuilder<T>
+export type RelationshipHelper<Props = unknown> =
+  /**
+   * @example
+   * ```ts
+   * rel('a', 'b')
+   * ```
+   *
+   * @example
+   * ```ts
+   * rel('a', 'b', {
+   *   title: 'title',
+   *   tags: ['tag1'],
+   * })
+   * ```
+   */
+  <
+    T extends AnyTypes,
+    From extends string & T['Fqn'],
+    To extends string & T['Fqn'],
+  >(
+    from: From,
+    to: To,
+    titleOrProps?: string | Props,
+  ) => (builder: ModelBuilder<T>) => ModelBuilder<T>
 
-export type NestedRelationshipHelper<Props = unknown> = <T extends AnyTypesNested, To extends string & T['Fqn']>(
-  to: To,
-  titleOrProps?: string | Props,
-) => (builder: ModelBuilder<T>) => ModelBuilder<T>
+export type NestedRelationshipHelper<Props = unknown> =
+  /**
+   * @example
+   * ```ts
+   * el('a').with(
+   *   relTo('b')
+   * )
+   * ```
+   *
+   * @example
+   * ```ts
+   * el('a').with(
+   *   relTo('b', {
+   *     title: 'title',
+   *     tags: ['tag1'],
+   *   })
+   * )
+   * ```
+   */
+  <T extends AnyTypesNested, To extends string & T['Fqn']>(
+    to: To,
+    titleOrProps?: string | Props,
+  ) => (builder: ModelBuilder<T>) => ModelBuilder<T>
 
-type AddElementHelper<T = unknown> = <const Id extends string>(
-  id: ValidId<Id>,
-  titleOrProps?: string | T,
-) => AddElement<Id>
+type AddElementHelper<T = unknown> =
+  /**
+   * @example
+   * ```ts
+   * el('some.id')
+   * ```
+   *
+   * @example
+   * ```ts
+   * el('some.id', {
+   *   title: 'title',
+   *   tags: ['tag1'],
+   * })
+   * ```
+   */
+  <const Id extends string>(
+    id: ValidId<Id>,
+    titleOrProps?: string | T,
+  ) => AddElement<Id>
 
 export type AddElementHelpers<T extends AnyTypes> = T extends
   Types<infer Kinds extends string, any, any, any, any, any, any, any> ? {