@likec4/core 1.30.0 → 1.32.0

package/src/types/expression-model.ts

@@ -0,0 +1,292 @@
+import type { ExclusiveUnion } from './_common'
+import type * as aux from './aux'
+import type { AnyAux } from './aux'
+import type { PredicateSelector } from './expression'
+import { FqnRef } from './fqnRef'
+import type { WhereOperator } from './operators'
+import { type Icon } from './scalar'
+import type {
+  BorderStyle,
+  Color,
+  ElementShape,
+  RelationshipArrowType,
+  RelationshipLineType,
+  ShapeSize,
+} from './styles'
+
+export namespace ModelFqnExpr {
+  export type Wildcard = {
+    wildcard: true
+  }
+  export function isWildcard<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelFqnExpr.Wildcard {
+    return 'wildcard' in expr && expr.wildcard === true
+  }
+
+  export interface Ref<M extends AnyAux> {
+    ref: FqnRef.ModelRef<M>
+    selector?: PredicateSelector
+  }
+  export function isModelRef<A extends AnyAux>(ref: ModelExpression<A>): ref is ModelFqnExpr.Ref<A> {
+    return 'ref' in ref && FqnRef.isModelRef(ref.ref)
+  }
+
+  export interface ElementKindExpr<A extends AnyAux = AnyAux> {
+    elementKind: aux.ElementKind<A>
+    isEqual: boolean
+  }
+  export function isElementKindExpr<A extends AnyAux>(expr: ModelExpression<A>): expr is ElementKindExpr<A> {
+    return 'elementKind' in expr && 'isEqual' in expr
+  }
+
+  export interface ElementTagExpr<A extends AnyAux> {
+    elementTag: aux.Tag<A>
+    isEqual: boolean
+  }
+  export function isElementTagExpr<A extends AnyAux>(expr: ModelExpression<A>): expr is ElementTagExpr<A> {
+    return 'elementTag' in expr && 'isEqual' in expr
+  }
+
+  export type NonWildcard<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Ref: Ref<A>
+    ElementKind: ElementKindExpr<A>
+    ElementTag: ElementTagExpr<A>
+  }>
+
+  export interface Where<A extends AnyAux = AnyAux> {
+    where: {
+      expr: ExclusiveUnion<{
+        Wildcard: Wildcard
+        Ref: Ref<A>
+        ElementKind: ElementKindExpr<A>
+        ElementTag: ElementTagExpr<A>
+      }>
+      condition: WhereOperator<A>
+    }
+  }
+
+  export function isWhere<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelFqnExpr.Where<A> {
+    return 'where' in expr && is(expr.where.expr)
+  }
+
+  export interface Custom<A extends AnyAux = AnyAux> {
+    custom: {
+      expr: OrWhere<A>
+      title?: string
+      description?: string
+      technology?: string
+      notation?: string
+      shape?: ElementShape
+      color?: Color
+      icon?: Icon
+      border?: BorderStyle
+      opacity?: number
+      navigateTo?: aux.StrictViewId<A>
+      multiple?: boolean
+      size?: ShapeSize
+      padding?: ShapeSize
+      textSize?: ShapeSize
+    }
+  }
+
+  export function isCustom<A extends AnyAux>(expr: ModelExpression<A>): expr is Custom<A> {
+    return 'custom' in expr && (is(expr.custom.expr) || isWhere(expr.custom.expr))
+  }
+
+  export function is<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelFqnExpr<A> {
+    return isWildcard(expr)
+      || isModelRef(expr)
+      || isElementKindExpr(expr)
+      || isElementTagExpr(expr)
+  }
+
+  export type OrWhere<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Wildcard: ModelFqnExpr.Wildcard
+    Ref: ModelFqnExpr.Ref<A>
+    ElementKind: ElementKindExpr<A>
+    ElementTag: ElementTagExpr<A>
+    Where: ModelFqnExpr.Where<A>
+  }>
+
+  export type Any<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Wildcard: Wildcard
+    Ref: Ref<A>
+    ElementKind: ElementKindExpr<A>
+    ElementTag: ElementTagExpr<A>
+    Where: Where<A>
+    Custom: Custom<A>
+  }>
+
+  export function unwrap<A extends AnyAux>(
+    expr: ModelFqnExpr.Any<A>,
+  ): Wildcard | Ref<A> | ElementKindExpr<A> | ElementTagExpr<A> {
+    if (isCustom(expr)) {
+      expr = expr.custom.expr
+    }
+    if (isWhere(expr)) {
+      expr = expr.where.expr
+    }
+    return expr
+  }
+}
+
+export type ModelFqnExpr<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+  Wildcard: ModelFqnExpr.Wildcard
+  Ref: ModelFqnExpr.Ref<A>
+  ElementKind: ModelFqnExpr.ElementKindExpr<A>
+  ElementTag: ModelFqnExpr.ElementTagExpr<A>
+}>
+
+export namespace ModelRelationExpr {
+  export type Endpoint<A extends AnyAux = AnyAux> = ModelFqnExpr.Where<A>['where']['expr']
+
+  export interface Direct<A extends AnyAux = AnyAux> {
+    source: Endpoint<A>
+    target: Endpoint<A>
+    isBidirectional?: boolean
+  }
+  export function isDirect<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.Direct<A> {
+    return 'source' in expr && 'target' in expr
+  }
+  export interface Incoming<A extends AnyAux = AnyAux> {
+    incoming: Endpoint<A>
+  }
+  export function isIncoming<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.Incoming<A> {
+    return 'incoming' in expr
+  }
+  export interface Outgoing<A extends AnyAux = AnyAux> {
+    outgoing: Endpoint<A>
+  }
+  export function isOutgoing<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.Outgoing<A> {
+    return 'outgoing' in expr
+  }
+  export interface InOut<A extends AnyAux = AnyAux> {
+    inout: Endpoint<A>
+  }
+  export function isInOut<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.InOut<A> {
+    return 'inout' in expr
+  }
+  export interface Where<A extends AnyAux = AnyAux> {
+    where: {
+      expr: ExclusiveUnion<{
+        Direct: ModelRelationExpr.Direct<A>
+        Incoming: ModelRelationExpr.Incoming<A>
+        Outgoing: ModelRelationExpr.Outgoing<A>
+        InOut: ModelRelationExpr.InOut<A>
+      }>
+      condition: WhereOperator<A>
+    }
+  }
+  export function isWhere<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.Where<A> {
+    return 'where' in expr &&
+      (isDirect(expr.where.expr) || isIncoming(expr.where.expr) || isOutgoing(expr.where.expr) ||
+        isInOut(expr.where.expr))
+  }
+
+  export interface Custom<A extends AnyAux = AnyAux> {
+    customRelation: {
+      expr: OrWhere<A>
+      title?: string
+      description?: string
+      technology?: string
+      notation?: string
+      // Link to dynamic view
+      navigateTo?: aux.StrictViewId<A>
+      // Notes for walkthrough
+      notes?: string
+      color?: Color
+      line?: RelationshipLineType
+      head?: RelationshipArrowType
+      tail?: RelationshipArrowType
+    }
+  }
+
+  export function isCustom<A extends AnyAux>(expr: ModelExpression<A>): expr is Custom<A> {
+    return 'customRelation' in expr
+  }
+
+  export function is<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr<A> {
+    return isDirect(expr)
+      || isIncoming(expr)
+      || isOutgoing(expr)
+      || isInOut(expr)
+  }
+
+  export type OrWhere<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Direct: Direct<A>
+    Incoming: Incoming<A>
+    Outgoing: Outgoing<A>
+    InOut: InOut<A>
+    Where: Where<A>
+  }>
+
+  export type Any<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Direct: Direct<A>
+    Incoming: Incoming<A>
+    Outgoing: Outgoing<A>
+    InOut: InOut<A>
+    Where: Where<A>
+    Custom: Custom<A>
+  }>
+
+  export function unwrap<A extends AnyAux>(
+    expr: ModelRelationExpr.Any<A>,
+  ): Direct<A> | Incoming<A> | Outgoing<A> | InOut<A> {
+    if (isCustom(expr)) {
+      expr = expr.customRelation.expr
+    }
+    if (isWhere(expr)) {
+      expr = expr.where.expr
+    }
+    return expr
+  }
+}
+
+export type ModelRelationExpr<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+  Direct: ModelRelationExpr.Direct<A>
+  Incoming: ModelRelationExpr.Incoming<A>
+  Outgoing: ModelRelationExpr.Outgoing<A>
+  InOut: ModelRelationExpr.InOut<A>
+}>
+
+/**
+ * Represents a version 2 expression which can be one of several types.
+ *
+ * @template D - The type for the deployment FQN, defaults to `Fqn`.
+ * @template M - The type for the model FQN, defaults to `Fqn`.
+ */
+export type ModelExpression<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+  Wildcard: ModelFqnExpr.Wildcard
+  Ref: ModelFqnExpr.Ref<A>
+  ElementKind: ModelFqnExpr.ElementKindExpr<A>
+  ElementTag: ModelFqnExpr.ElementTagExpr<A>
+  Custom: ModelFqnExpr.Custom<A>
+  Direct: ModelRelationExpr.Direct<A>
+  Incoming: ModelRelationExpr.Incoming<A>
+  Outgoing: ModelRelationExpr.Outgoing<A>
+  InOut: ModelRelationExpr.InOut<A>
+  Where: ModelExpression.Where<A>
+  CustomRelation: ModelRelationExpr.Custom<A>
+}>
+
+export namespace ModelExpression {
+  export type Where<A extends AnyAux = AnyAux> = ModelFqnExpr.Where<A> | ModelRelationExpr.Where<A>
+  export function isWhere<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelExpression.Where<A> {
+    return 'where' in expr
+  }
+
+  export function isRelationWhere<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.Where<A> {
+    return ModelRelationExpr.isWhere(expr)
+  }
+
+  export function isFqnExprWhere<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelFqnExpr.Where<A> {
+    return ModelFqnExpr.isWhere(expr)
+  }
+
+  export function isFqnExpr<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelFqnExpr.Any<A> {
+    return ModelFqnExpr.is(expr) || ModelFqnExpr.isWhere(expr) || ModelFqnExpr.isCustom(expr)
+  }
+
+  export function isRelationExpr<A extends AnyAux>(expr: ModelExpression<A>): expr is ModelRelationExpr.Any<A> {
+    return ModelRelationExpr.is(expr) || ModelRelationExpr.isWhere(expr) || ModelRelationExpr.isCustom(expr)
+  }
+}

package/src/types/expression.ts

@@ -0,0 +1,311 @@
+import type { ExclusiveUnion } from './_common'
+import type * as aux from './aux'
+import type { AnyAux } from './aux'
+import { FqnRef } from './fqnRef'
+import type { WhereOperator } from './operators'
+import { type Icon } from './scalar'
+import type {
+  BorderStyle,
+  Color,
+  ElementShape,
+  RelationshipArrowType,
+  RelationshipLineType,
+  ShapeSize,
+} from './styles'
+
+export type PredicateSelector =
+  | 'children' // ele.*
+  | 'expanded' // ele._
+  | 'descendants' // ele.**
+
+export namespace FqnExpr {
+  export type Wildcard = {
+    wildcard: true
+  }
+  export function isWildcard<A extends AnyAux>(expr: Expression<A>): expr is FqnExpr.Wildcard {
+    return 'wildcard' in expr && expr.wildcard === true
+  }
+
+  export interface ModelRef<M extends AnyAux = AnyAux> {
+    ref: FqnRef.ModelRef<M>
+    selector?: PredicateSelector
+  }
+  export function isModelRef<A extends AnyAux>(ref: Expression<A>): ref is FqnExpr.ModelRef<A> {
+    return 'ref' in ref && FqnRef.isModelRef(ref.ref)
+  }
+
+  export interface DeploymentRef<A extends AnyAux = AnyAux> {
+    ref: FqnRef.DeploymentRef<A>
+    selector?: PredicateSelector
+  }
+  export function isDeploymentRef<A extends AnyAux>(expr: Expression<A>): expr is FqnExpr.DeploymentRef<A> {
+    return 'ref' in expr && FqnRef.isDeploymentRef(expr.ref)
+  }
+
+  export interface ElementKindExpr<A extends AnyAux = AnyAux> {
+    elementKind: aux.ElementKind<A>
+    isEqual: boolean
+  }
+  export function isElementKindExpr<A extends AnyAux>(expr: Expression<A>): expr is ElementKindExpr<A> {
+    return 'elementKind' in expr && 'isEqual' in expr
+  }
+
+  export interface ElementTagExpr<A extends AnyAux = AnyAux> {
+    elementTag: aux.Tag<A>
+    isEqual: boolean
+  }
+  export function isElementTagExpr<A extends AnyAux>(expr: Expression<A>): expr is ElementTagExpr<A> {
+    return 'elementTag' in expr && 'isEqual' in expr
+  }
+
+  export type NonWildcard<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    ModelRef: ModelRef<A>
+    DeploymentRef: DeploymentRef<A>
+    ElementKind: ElementKindExpr<A>
+    ElementTag: ElementTagExpr<A>
+  }>
+
+  export interface Where<A extends AnyAux = AnyAux> {
+    where: {
+      expr: ExclusiveUnion<{
+        Wildcard: Wildcard
+        ModelRef: ModelRef<A>
+        DeploymentRef: DeploymentRef<A>
+        ElementKind: ElementKindExpr<A>
+        ElementTag: ElementTagExpr<A>
+      }>
+      condition: WhereOperator<A>
+    }
+  }
+
+  export function isWhere<A extends AnyAux>(expr: Expression<A>): expr is FqnExpr.Where<A> {
+    return 'where' in expr && is(expr.where.expr)
+  }
+
+  export interface Custom<A extends AnyAux = AnyAux> {
+    custom: {
+      expr: OrWhere<A>
+      title?: string
+      description?: string
+      technology?: string
+      notation?: string
+      shape?: ElementShape
+      color?: Color
+      icon?: Icon
+      border?: BorderStyle
+      opacity?: number
+      navigateTo?: aux.StrictViewId<A>
+      multiple?: boolean
+      size?: ShapeSize
+      padding?: ShapeSize
+      textSize?: ShapeSize
+    }
+  }
+
+  export function isCustom<A extends AnyAux>(expr: Expression<A>): expr is Custom<A> {
+    return 'custom' in expr && (is(expr.custom.expr) || isWhere(expr.custom.expr))
+  }
+
+  export function is<A extends AnyAux>(expr: Expression<A>): expr is FqnExpr<A> {
+    return isWildcard(expr)
+      || isModelRef(expr)
+      || isDeploymentRef(expr)
+      || isElementKindExpr(expr)
+      || isElementTagExpr(expr)
+  }
+
+  export type OrWhere<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Wildcard: FqnExpr.Wildcard
+    ModelRef: FqnExpr.ModelRef<A>
+    DeploymentRef: FqnExpr.DeploymentRef<A>
+    ElementKind: ElementKindExpr<A>
+    ElementTag: ElementTagExpr<A>
+    Where: FqnExpr.Where<A>
+  }>
+
+  export type Any<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Wildcard: Wildcard
+    ModelRef: ModelRef<A>
+    DeploymentRef: DeploymentRef<A>
+    ElementKind: ElementKindExpr<A>
+    ElementTag: ElementTagExpr<A>
+    Where: Where<A>
+    Custom: Custom<A>
+  }>
+
+  export function unwrap<A extends AnyAux>(
+    expr: FqnExpr.Any<A>,
+  ): Wildcard | ModelRef<A> | DeploymentRef<A> | ElementKindExpr<A> | ElementTagExpr<A> {
+    if (isCustom(expr)) {
+      expr = expr.custom.expr
+    }
+    if (isWhere(expr)) {
+      expr = expr.where.expr
+    }
+    return expr
+  }
+}
+
+export type FqnExpr<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+  Wildcard: FqnExpr.Wildcard
+  ModelRef: FqnExpr.ModelRef<A>
+  DeploymentRef: FqnExpr.DeploymentRef<A>
+  ElementKind: FqnExpr.ElementKindExpr<A>
+  ElementTag: FqnExpr.ElementTagExpr<A>
+}>
+
+export namespace RelationExpr {
+  export type Endpoint<A extends AnyAux = AnyAux> = FqnExpr.Where<A>['where']['expr']
+
+  export interface Direct<A extends AnyAux = AnyAux> {
+    source: Endpoint<A>
+    target: Endpoint<A>
+    isBidirectional?: boolean
+  }
+  export function isDirect<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.Direct<A> {
+    return 'source' in expr && 'target' in expr
+  }
+  export interface Incoming<A extends AnyAux = AnyAux> {
+    incoming: Endpoint<A>
+  }
+  export function isIncoming<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.Incoming<A> {
+    return 'incoming' in expr
+  }
+  export interface Outgoing<A extends AnyAux = AnyAux> {
+    outgoing: Endpoint<A>
+  }
+  export function isOutgoing<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.Outgoing<A> {
+    return 'outgoing' in expr
+  }
+  export interface InOut<A extends AnyAux = AnyAux> {
+    inout: Endpoint<A>
+  }
+  export function isInOut<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.InOut<A> {
+    return 'inout' in expr
+  }
+  export interface Where<A extends AnyAux = AnyAux> {
+    where: {
+      expr: ExclusiveUnion<{
+        Direct: RelationExpr.Direct<A>
+        Incoming: RelationExpr.Incoming<A>
+        Outgoing: RelationExpr.Outgoing<A>
+        InOut: RelationExpr.InOut<A>
+      }>
+      condition: WhereOperator<A>
+    }
+  }
+  export function isWhere<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.Where<A> {
+    return 'where' in expr &&
+      (isDirect(expr.where.expr) || isIncoming(expr.where.expr) || isOutgoing(expr.where.expr) ||
+        isInOut(expr.where.expr))
+  }
+
+  export interface Custom<A extends AnyAux = AnyAux> {
+    customRelation: {
+      expr: OrWhere<A>
+      title?: string
+      description?: string
+      technology?: string
+      notation?: string
+      // Link to dynamic view
+      navigateTo?: aux.StrictViewId<A>
+      // Notes for walkthrough
+      notes?: string
+      color?: Color
+      line?: RelationshipLineType
+      head?: RelationshipArrowType
+      tail?: RelationshipArrowType
+    }
+  }
+
+  export function isCustom<A extends AnyAux>(expr: Expression<A>): expr is Custom<A> {
+    return 'customRelation' in expr
+  }
+
+  export function is<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr<A> {
+    return isDirect(expr)
+      || isIncoming(expr)
+      || isOutgoing(expr)
+      || isInOut(expr)
+  }
+
+  export type OrWhere<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Direct: Direct<A>
+    Incoming: Incoming<A>
+    Outgoing: Outgoing<A>
+    InOut: InOut<A>
+    Where: Where<A>
+  }>
+
+  export type Any<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+    Direct: Direct<A>
+    Incoming: Incoming<A>
+    Outgoing: Outgoing<A>
+    InOut: InOut<A>
+    Where: Where<A>
+    Custom: Custom<A>
+  }>
+
+  export function unwrap<A extends AnyAux>(
+    expr: RelationExpr.Any<A>,
+  ): Direct<A> | Incoming<A> | Outgoing<A> | InOut<A> {
+    if (isCustom(expr)) {
+      expr = expr.customRelation.expr
+    }
+    if (isWhere(expr)) {
+      expr = expr.where.expr
+    }
+    return expr
+  }
+}
+
+export type RelationExpr<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+  Direct: RelationExpr.Direct<A>
+  Incoming: RelationExpr.Incoming<A>
+  Outgoing: RelationExpr.Outgoing<A>
+  InOut: RelationExpr.InOut<A>
+}>
+
+/**
+ * Represents a version 2 expression which can be one of several types.
+ *
+ * @template D - The type for the deployment FQN, defaults to `Fqn`.
+ * @template M - The type for the model FQN, defaults to `Fqn`.
+ */
+export type Expression<A extends AnyAux = AnyAux> = ExclusiveUnion<{
+  Wildcard: FqnExpr.Wildcard
+  ModelRef: FqnExpr.ModelRef<A>
+  DeploymentRef: FqnExpr.DeploymentRef<A>
+  ElementKind: FqnExpr.ElementKindExpr<A>
+  ElementTag: FqnExpr.ElementTagExpr<A>
+  Custom: FqnExpr.Custom<A>
+  Direct: RelationExpr.Direct<A>
+  Incoming: RelationExpr.Incoming<A>
+  Outgoing: RelationExpr.Outgoing<A>
+  InOut: RelationExpr.InOut<A>
+  Where: Expression.Where<A>
+  CustomRelation: RelationExpr.Custom<A>
+}>
+
+export namespace Expression {
+  export type Where<A extends AnyAux = AnyAux> = FqnExpr.Where<A> | RelationExpr.Where<A>
+  export function isWhere<A extends AnyAux>(expr: Expression<A>): expr is Expression.Where<A> {
+    return 'where' in expr
+  }
+
+  export function isRelationWhere<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.Where<A> {
+    return RelationExpr.isWhere(expr)
+  }
+
+  export function isFqnExprWhere<A extends AnyAux>(expr: Expression<A>): expr is FqnExpr.Where<A> {
+    return FqnExpr.isWhere(expr)
+  }
+
+  export function isFqnExpr<A extends AnyAux>(expr: Expression<A>): expr is FqnExpr.Any<A> {
+    return FqnExpr.is(expr) || FqnExpr.isWhere(expr) || FqnExpr.isCustom(expr)
+  }
+
+  export function isRelation<A extends AnyAux>(expr: Expression<A>): expr is RelationExpr.Any<A> {
+    return RelationExpr.is(expr) || RelationExpr.isWhere(expr) || RelationExpr.isCustom(expr)
+  }
+}

package/src/types/fqnRef.ts

@@ -0,0 +1,88 @@
+import { isString } from 'remeda'
+import type { ExclusiveUnion } from './_common'
+import type * as aux from './aux'
+import type { AnyAux, Unknown } from './aux'
+import { GlobalFqn } from './scalar'
+
+export namespace FqnRef {
+  /**
+   * Reference to logical model element
+   */
+  export interface ElementRef<A extends AnyAux = Unknown> {
+    project?: never
+    model: aux.ElementId<A>
+  }
+  export function isElementRef<A extends AnyAux>(ref: FqnRef<A>): ref is ElementRef<A> {
+    return 'model' in ref && !('project' in ref)
+  }
+
+  /**
+   * Reference to imported logical model element
+   */
+  export interface ImportRef<A extends AnyAux = Unknown> {
+    project: aux.ProjectId<A>
+    model: aux.ElementId<A>
+  }
+  export function isImportRef<A extends AnyAux>(ref: FqnRef<A>): ref is ImportRef<A> {
+    return 'project' in ref && 'model' in ref
+  }
+
+  export function flatten<A extends AnyAux>(ref: FqnRef<A>): aux.StrictFqn<A> {
+    if (isString(ref)) {
+      throw new Error(`Expected FqnRef, got: "${ref}"`)
+    }
+    if (isImportRef(ref)) {
+      return GlobalFqn(ref.project, ref.model) as unknown as aux.StrictFqn<A>
+    }
+    if (isElementRef(ref)) {
+      return ref.model as unknown as aux.StrictFqn<A>
+    }
+    throw new Error('Expected FqnRef.ModelRef or FqnRef.ImportRef')
+  }
+
+  export type ModelRef<A extends AnyAux = Unknown> = ImportRef<A> | ElementRef<A>
+  export function isModelRef<A extends AnyAux>(ref: FqnRef<A>): ref is ModelRef<A> {
+    return isElementRef(ref) || isImportRef(ref)
+  }
+
+  /**
+   * Represents a reference to an instance within a deployment.
+   *
+   * @template D - The type representing the deployment fqn. Defaults to `Fqn`.
+   * @template M - The type representing the model fqn. Defaults to `Fqn`.
+   *
+   * @property {D} deployment - TThe fully qualified name (FQN) of the deployed instance.
+   * @property {M} element - The element reference within the deployment.
+   */
+  export interface InsideInstanceRef<A extends AnyAux = Unknown> {
+    deployment: aux.DeploymentId<A>
+    element: aux.ElementId<A>
+  }
+  export function isInsideInstanceRef<A extends AnyAux>(ref: FqnRef<A>): ref is InsideInstanceRef<A> {
+    return 'deployment' in ref && 'element' in ref
+  }
+
+  /**
+   * Represents a reference to a deployment element.
+   *
+   * @template F - The type of the fully qualified name (FQN) of the deployment element. Defaults to `Fqn`.
+   * @property {F} deployment - The fully qualified name (FQN) of the deployment element.
+   */
+  export interface DeploymentElementRef<A extends AnyAux> {
+    deployment: aux.DeploymentId<A>
+    element?: never
+  }
+  export function isDeploymentElementRef<A extends AnyAux>(ref: FqnRef<A>): ref is DeploymentElementRef<A> {
+    return 'deployment' in ref && !('element' in ref)
+  }
+
+  export type DeploymentRef<A extends AnyAux> = DeploymentElementRef<A> | InsideInstanceRef<A>
+  export function isDeploymentRef<A extends AnyAux>(ref: FqnRef<A>): ref is DeploymentRef<A> {
+    return isDeploymentElementRef(ref) || isInsideInstanceRef(ref)
+  }
+}
+
+export type FqnRef<A extends AnyAux = Unknown> = ExclusiveUnion<{
+  DeploymentRef: FqnRef.DeploymentRef<A>
+  ModelRef: FqnRef.ModelRef<A>
+}>