@likec4/core 0.29.0 → 0.31.0

package/README.md

@@ -0,0 +1,3 @@
+# @likec4/core
+
+Core likec4 types, errors, functions and utilities.

package/dist/compute-view/compute-element-view.js

@@ -12,7 +12,7 @@ import { invariant } from '../errors';
 function transformToNodes(elementsIterator) {
     return Array.from(elementsIterator)
         .sort(compareByFqnHierarchically)
-        .reduce((map, { id, kind, title, color, shape, description }) => {
+        .reduce((map, { id, color, shape, ...el }) => {
         let parent = parentFqn(id);
         while (parent) {
             if (map.has(parent)) {
@@ -26,14 +26,12 @@ function transformToNodes(elementsIterator) {
             parentNd.children.push(id);
         }
         const node = {
+            ...el,
             id,
-            kind,
             parent,
-            title,
             color: color ?? DefaultThemeColor,
             shape: shape ?? DefaultElementShape,
-            children: [],
-            ...(description ? { description } : {})
+            children: []
         };
         map.set(id, node);
         return map;

package/dist/errors/index.d.ts

@@ -1,3 +1,4 @@
 export * from './_base';
 export * from './invariant';
+export * from './model-index';
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -1,3 +1,4 @@
 export * from './_base';
 export * from './invariant';
+export * from './model-index';
 //# sourceMappingURL=index.js.map

package/dist/errors/model-index.d.ts

@@ -0,0 +1,3 @@
+export declare const InvalidModelError: import("modern-errors").ErrorSubclassCore<[], {}, import("modern-errors").CustomClass>;
+export declare function ensureModel(condition: any, message?: string): asserts condition;
+//# sourceMappingURL=model-index.d.ts.map

package/dist/errors/model-index.js

@@ -0,0 +1,14 @@
+import { BaseError } from './_base';
+export const InvalidModelError = BaseError.subclass('InvalidModelError');
+export function ensureModel(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+condition, 
+// 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) {
+    if (condition) {
+        return;
+    }
+    throw new InvalidModelError(message ?? 'ModelIndex Invariant failed');
+}
+//# sourceMappingURL=model-index.js.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './types';
+export * from './types';
 export * from './compute-view';
 export * from './utils';
 export * from './model-index';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './types';
 export * from './compute-view';
 export * from './utils';
 export * from './model-index';

package/dist/model-index/ModelIndex.d.ts

@@ -8,7 +8,7 @@ export default class ModelIndex {
     private _elements;
     private _relations;
     get relations(): Relation[];
-    filterRelations: (predicate: (r: Relation) => boolean) => Relation[];
+    filterRelations(predicate: (r: Relation) => boolean): Relation[];
     static from({ elements, relations }: ModelInput): ModelIndex;
     addElement(el: Element): void;
     private locateTrie;
@@ -18,9 +18,10 @@ export default class ModelIndex {
     /**
      * Ancestors from closest parent to root
      */
-    ancestors: (id: Fqn) => Element[];
+    ancestors(id: Fqn): Element[];
     rootElements(): Element[];
     get elements(): Element[];
+    hasElement(fqn: Fqn): boolean;
     addRelation(rel: Relation): void;
 }
 export {};

package/dist/model-index/ModelIndex.js

@@ -1,6 +1,6 @@
-import { values } from 'remeda';
-import { invariant } from '../errors';
-import { parentFqn } from '../utils/fqn';
+import { pipe, sort, values } from 'remeda';
+import { InvalidModelError, ensureModel } from '../errors';
+import { compareByFqnHierarchically, parentFqn } from '../utils/fqn';
 function childrenOf(trie) {
     const children = [];
     for (const { el } of values(trie.children)) {
@@ -24,12 +24,13 @@ export default class ModelIndex {
     get relations() {
         return Array.from(this._relations.values());
     }
-    filterRelations = (predicate) => {
+    filterRelations(predicate) {
         return this.relations.filter(predicate);
-    };
+    }
     static from({ elements, relations }) {
         const index = new ModelIndex();
-        for (const el of values(elements)) {
+        const sortedElements = pipe(values(elements), sort(compareByFqnHierarchically));
+        for (const el of sortedElements) {
             index.addElement(el);
         }
         for (const rel of values(relations)) {
@@ -38,8 +39,8 @@ export default class ModelIndex {
         return index;
     }
     addElement(el) {
-        if (this._elements.has(el.id)) {
-            throw new Error(`Element already exists with id ${el.id}`);
+        if (this.hasElement(el.id)) {
+            throw new InvalidModelError(`Element already exists with id ${el.id}`);
         }
         const path = asPath(el.id);
         let scope = this.root;
@@ -57,7 +58,7 @@ export default class ModelIndex {
         let scope = this.root;
         for (const name of asPath(id)) {
             const next = scope.children[name];
-            invariant(next, `Invalid index, Element not found at path ${name} of ${id}`);
+            ensureModel(next, `Invalid index, Element not found at path ${name} of ${id}`);
             scope = next;
         }
         return scope;
@@ -65,7 +66,7 @@ export default class ModelIndex {
     find = (id) => {
         const el = this._elements.get(id);
         if (!el) {
-            throw new Error(`Element not found ${id}`);
+            throw new InvalidModelError(`Element not found ${id}`);
         }
         return el;
     };
@@ -80,7 +81,7 @@ export default class ModelIndex {
     /**
      * Ancestors from closest parent to root
      */
-    ancestors = (id) => {
+    ancestors(id) {
         const path = asPath(id);
         const ancestors = [];
         // The root
@@ -93,18 +94,14 @@ export default class ModelIndex {
         let trie = this.root;
         while (name) {
             const next = trie.children[name];
-            if (!next) {
-                throw new Error(`Invalid index, Element not found at path ${name} of ${id}`);
-            }
+            ensureModel(next, `Invalid index, Element not found at path ${name} of ${id}`);
             trie = next;
-            if (!trie.el) {
-                throw new Error(`invalid index, no element ${name} found in ${id}`);
-            }
+            ensureModel(trie.el, `invalid index, no element ${name} found in ${id}`);
             ancestors.unshift(trie.el);
             name = path.shift();
         }
         return ancestors;
-    };
+    }
     // tagged = (tag?: Tag): TaggedResult => {
     //   return tag ? {
     //     elements: [...this._taggedElements.get(tag)?.values() ?? []],
@@ -120,16 +117,16 @@ export default class ModelIndex {
     get elements() {
         return Array.from(this._elements.values());
     }
-    // hasElement(fqn: Fqn): boolean {
-    //   return fqn in this._elements
-    // }
+    hasElement(fqn) {
+        return this._elements.has(fqn);
+    }
     addRelation(rel) {
         // Validate source and target
-        if (!this._elements.has(rel.source)) {
-            throw new Error(`Invalid index, source of relation not found ${rel.source}`);
+        if (!this.hasElement(rel.source)) {
+            throw new InvalidModelError(`Source of relation not found ${rel.source}`);
         }
-        if (!this._elements.has(rel.target)) {
-            throw new Error(`Invalid index, target of relation not found ${rel.target}`);
+        if (!this.hasElement(rel.target)) {
+            throw new InvalidModelError(`Target of relation not found ${rel.target}`);
         }
         this._relations.set(rel.id, rel);
         // for (const tag of rel.tags) {

package/dist/types/_common.d.ts

@@ -0,0 +1,2 @@
+export type NonEmptyArray<T> = [T, ...T[]];
+//# sourceMappingURL=_common.d.ts.map

package/dist/types/_common.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=_common.js.map

package/dist/types/computed-view.d.ts

@@ -2,6 +2,7 @@ import type { Opaque } from './opaque';
 import type { ElementKind, ElementShape, Fqn, Tag, ThemeColor } from './element';
 import type { RelationID } from './relation';
 import type { ElementView, ViewID, ViewRuleAutoLayout } from './view';
+import type { NonEmptyArray } from './_common';
 export type NodeId = Fqn;
 export type EdgeId = Opaque<string, 'EdgeId'>;
 export interface ComputedNode {
@@ -9,9 +10,10 @@ export interface ComputedNode {
     kind: ElementKind;
     parent: NodeId | null;
     title: string;
-    description?: string;
-    technology?: string;
-    tags?: Tag[];
+    description: string | null;
+    technology: string | null;
+    tags: NonEmptyArray<Tag> | null;
+    links: NonEmptyArray<string> | null;
     children: NodeId[];
     shape: ElementShape;
     color: ThemeColor;

package/dist/types/element.d.ts

@@ -1,7 +1,11 @@
+import type { NonEmptyArray } from '.';
 import type { Opaque } from './opaque';
 export type Fqn = Opaque<string, 'Fqn'>;
-export declare function Fqn(name: string, parent?: Fqn | null): Fqn;
+export declare function AsFqn(name: string, parent?: Fqn | null): Fqn;
 export type ElementKind = Opaque<string, 'ElementKind'>;
+/**
+ * TailwindCSS based color palette
+ */
 export type ThemeColor = 'amber' | 'blue' | 'gray' | 'slate' | 'green' | 'indigo' | 'muted' | 'primary' | 'red' | 'secondary' | 'sky';
 export type ElementShape = 'rectangle' | 'person' | 'browser' | 'mobile' | 'cylinder' | 'storage' | 'queue';
 export declare const DefaultThemeColor: ThemeColor;
@@ -18,9 +22,10 @@ export interface Element {
     readonly id: Fqn;
     readonly kind: ElementKind;
     readonly title: string;
-    readonly description?: string;
-    readonly technology?: string;
-    readonly tags?: Tag[];
+    readonly description: string | null;
+    readonly technology: string | null;
+    readonly tags: NonEmptyArray<Tag> | null;
+    readonly links: NonEmptyArray<string> | null;
     readonly shape?: ElementShape;
     readonly color?: ThemeColor;
 }

package/dist/types/element.js

@@ -1,4 +1,4 @@
-export function Fqn(name, parent) {
+export function AsFqn(name, parent) {
     return (parent ? parent + '.' + name : name);
 }
 export const DefaultThemeColor = 'primary';

package/dist/types/expression.d.ts

@@ -1,5 +1,5 @@
 import type { ElementKind, Fqn, Tag } from './element';
-interface BaseExr {
+interface BaseExpr {
     element?: never;
     elementKind?: never;
     elementTag?: never;
@@ -12,41 +12,41 @@ interface BaseExr {
     incoming?: never;
     outgoing?: never;
 }
-export interface ElementRefExpr extends Omit<BaseExr, 'element' | 'isDescedants'> {
+export interface ElementRefExpr extends Omit<BaseExpr, 'element' | 'isDescedants'> {
     element: Fqn;
     isDescedants: boolean;
 }
 export declare function isElementRef(expr: Expression): expr is ElementRefExpr;
-export interface WildcardExpr extends Omit<BaseExr, 'wildcard'> {
+export interface WildcardExpr extends Omit<BaseExpr, 'wildcard'> {
     wildcard: true;
 }
 export declare function isWildcard(expr: Expression): expr is WildcardExpr;
-export interface ElementKindExpr extends Omit<BaseExr, 'elementKind' | 'isEqual'> {
+export interface ElementKindExpr extends Omit<BaseExpr, 'elementKind' | 'isEqual'> {
     elementKind: ElementKind;
     isEqual: boolean;
 }
 export declare function isElementKindExpr(expr: Expression): expr is ElementKindExpr;
-export interface ElementTagExpr extends Omit<BaseExr, 'elementTag' | 'isEqual'> {
+export interface ElementTagExpr extends Omit<BaseExpr, 'elementTag' | 'isEqual'> {
     elementTag: Tag;
     isEqual: boolean;
 }
 export declare function isElementTagExpr(expr: Expression): expr is ElementTagExpr;
 export type ElementExpression = ElementRefExpr | WildcardExpr | ElementKindExpr | ElementTagExpr;
 export declare function isElement(expr: Expression): expr is ElementExpression;
-export interface RelationExpr extends Omit<BaseExr, 'source' | 'target'> {
+export interface RelationExpr extends Omit<BaseExpr, 'source' | 'target'> {
     source: ElementExpression;
     target: ElementExpression;
 }
 export declare function isRelation(expr: Expression): expr is RelationExpr;
-export interface InOutExpr extends Omit<BaseExr, 'inout'> {
+export interface InOutExpr extends Omit<BaseExpr, 'inout'> {
     inout: ElementExpression;
 }
 export declare function isInOut(expr: Expression): expr is InOutExpr;
-export interface IncomingExpr extends Omit<BaseExr, 'incoming'> {
+export interface IncomingExpr extends Omit<BaseExpr, 'incoming'> {
     incoming: ElementExpression;
 }
 export declare function isIncoming(expr: Expression): expr is IncomingExpr;
-export interface OutgoingExpr extends Omit<BaseExr, 'outgoing'> {
+export interface OutgoingExpr extends Omit<BaseExpr, 'outgoing'> {
     outgoing: ElementExpression;
 }
 export declare function isOutgoing(expr: Expression): expr is OutgoingExpr;

package/dist/types/index.d.ts

@@ -1,5 +1,7 @@
-export { Fqn, DefaultThemeColor, DefaultElementShape } from './element';
-export { isViewRuleExpression, isViewRuleStyle } from './view';
+export { AsFqn, DefaultThemeColor, DefaultElementShape } from './element';
+export { isViewRuleExpression, isViewRuleAutoLayout, isViewRuleStyle } from './view';
+export * as Expr from './expression';
+export type * from './_common';
 export type * from './opaque';
 export type * from './element';
 export type * from './relation';

package/dist/types/index.js

@@ -1,3 +1,4 @@
-export { Fqn, DefaultThemeColor, DefaultElementShape } from './element';
-export { isViewRuleExpression, isViewRuleStyle } from './view';
+export { AsFqn, DefaultThemeColor, DefaultElementShape } from './element';
+export { isViewRuleExpression, isViewRuleAutoLayout, isViewRuleStyle } from './view';
+export * as Expr from './expression';
 //# sourceMappingURL=index.js.map

package/dist/types/view.d.ts

@@ -1,6 +1,7 @@
 import type { Opaque } from './opaque';
-import type { ElementShape, Fqn, ThemeColor } from './element';
+import type { ElementShape, Fqn, Tag, ThemeColor } from './element';
 import type { ElementExpression, Expression } from './expression';
+import type { NonEmptyArray } from './_common';
 export type ViewID = Opaque<string, 'ViewID'>;
 export interface ViewRuleExpression {
     isInclude: boolean;
@@ -23,8 +24,10 @@ export type ViewRule = ViewRuleExpression | ViewRuleStyle | ViewRuleAutoLayout;
 export interface ElementView {
     readonly id: ViewID;
     readonly viewOf?: Fqn;
-    readonly title?: string;
-    readonly description?: string;
+    readonly title: string | null;
+    readonly description: string | null;
+    readonly tags: NonEmptyArray<Tag> | null;
+    readonly links: NonEmptyArray<string> | null;
     readonly rules: ViewRule[];
 }
 //# sourceMappingURL=view.d.ts.map

package/dist/utils/fqn.d.ts

@@ -6,6 +6,16 @@ export declare function isDescendantOf(ancestors: Element[]): (e: Element) => bo
 export declare function notDescendantOf(ancestors: Element[]): (e: Element) => boolean;
 export declare function commonAncestor(first: Fqn, second: Fqn): Fqn | null;
 export declare function parentFqn(fqn: Fqn): Fqn | null;
+/**
+ * Compares two fully qualified names (fqns) hierarchically based on their depth.
+ * From parent nodes to leaves
+ *
+ * @param {string} a - The first fqn to compare.
+ * @param {string} b - The second fqn to compare.
+ * @returns {number} - 0 if the fqns have the same depth.
+ *                    - Positive number if a is deeper than b.
+ *                    - Negative number if b is deeper than a.
+ */
 export declare const compareFqnHierarchically: (a: string, b: string) => number;
 export declare const compareByFqnHierarchically: <T extends {
     id: Fqn;

package/dist/utils/fqn.js

@@ -56,6 +56,16 @@ export function parentFqn(fqn) {
     }
     return null;
 }
+/**
+ * Compares two fully qualified names (fqns) hierarchically based on their depth.
+ * From parent nodes to leaves
+ *
+ * @param {string} a - The first fqn to compare.
+ * @param {string} b - The second fqn to compare.
+ * @returns {number} - 0 if the fqns have the same depth.
+ *                    - Positive number if a is deeper than b.
+ *                    - Negative number if b is deeper than a.
+ */
 export const compareFqnHierarchically = (a, b) => {
     const depthA = a.split('.').length;
     const depthB = b.split('.').length;

package/dist/utils/guards.d.ts

@@ -1,4 +1,6 @@
+import type { NonEmptyArray } from "../types";
 export declare function isString(value: unknown): value is string;
 export declare function failExpectedNever(arg: never): never;
 export declare function ignoreNeverInRuntime(arg: never): void;
+export declare function isNonEmptyArray<A>(arr: ArrayLike<A>): arr is NonEmptyArray<A>;
 //# sourceMappingURL=guards.d.ts.map

package/dist/utils/guards.js

@@ -8,4 +8,7 @@ export function ignoreNeverInRuntime(arg) {
     console.warn(`Unexpected and ignored value: ${JSON.stringify(arg)}`);
     // throw new Error(`Unexpected value: ${arg}`);
 }
+export function isNonEmptyArray(arr) {
+    return arr.length > 0;
+}
 //# sourceMappingURL=guards.js.map

package/package.json

@@ -1,21 +1,15 @@
 {
   "name": "@likec4/core",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "license": "MIT",
-  "bugs": "https://github.com/likec4/likec4/issues",
   "homepage": "https://likec4.dev",
   "author": "Denis Davydkov <denis@davydkov.com>",
-  "files": [
-    "dist",
-    "!dist/__test__",
-    "!**/*.spec.*",
-    "!**/*.map"
-  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/likec4/likec4.git",
     "directory": "packages/core"
   },
+  "bugs": "https://github.com/likec4/likec4/issues",
   "scripts": {
     "compile": "tsc --noEmit",
     "build": "tsc",
@@ -25,6 +19,12 @@
     "test:watch": "run -T vitest",
     "clean": "run -T rimraf dist"
   },
+  "files": [
+    "dist",
+    "!dist/__test__",
+    "!**/*.spec.*",
+    "!**/*.map"
+  ],
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
@@ -93,7 +93,7 @@
     "@dagrejs/graphlib": "^2.1.13",
     "modern-errors": "^6.0.0",
     "rambdax": "^9.1.1",
-    "remeda": "^1.23.0"
+    "remeda": "^1.24.0"
   },
   "devDependencies": {
     "typescript": "^5.1.6"