Cyclic type definitions

packages/typir/src/graph/type-graph.ts

@@ -5,6 +5,7 @@
  ******************************************************************************/
 
 import { EdgeCachingInformation } from '../features/caching.js';
+import { assertTrue } from '../utils/utils.js';
 import { TypeEdge } from './type-edge.js';
 import { Type } from './type-node.js';
 
@@ -28,10 +29,11 @@ export class TypeGraph {
      * Therefore it is usually not needed to call this method in an other context.
      * @param type the new type
      * @param key an optional key to register the type, since it is allowed to register the same type with different keys in the graph
-     * TODO oder stattdessen einen ProxyType verwenden? wie funktioniert das mit isClassType und isSubType? wie funktioniert removeType?
      */
     addNode(type: Type, key?: string): void {
-        // TODO überprüfen, dass Identifiable-State erreicht ist??
+        if (!key) {
+            assertTrue(type.isInStateOrLater('Identifiable')); // the key of the type must be available!
+        }
         const mapKey = key ?? type.getIdentifier();
         if (this.nodes.has(mapKey)) {
             if (this.nodes.get(mapKey) === type) {
@@ -62,7 +64,7 @@ export class TypeGraph {
         const contained = this.nodes.delete(mapKey);
         if (contained) {
             this.listeners.slice().forEach(listener => listener.removedType(typeToRemove, mapKey));
-            typeToRemove.deconstruct();
+            typeToRemove.dispose();
         } else {
             throw new Error(`Type does not exist: ${mapKey}`);
         }

packages/typir/src/graph/type-node.ts

@@ -19,6 +19,10 @@ stateDiagram-v2
     Completed --> Invalid
     Identifiable --> Invalid
 ```
+ * A state is 'Completed', when all its dependencies are available, i.e. the types of all its properties are available.
+ * A state is 'Identifiable', when all those dependencies are available which are required to calculate the identifier of the type.
+ * A state is 'Invalid' otherwise.
+ * 'Invalid' is made explicit, since it might require less dependencies than 'Completed' and therefore speed-ups the resolution of dependencies.
  */
 export type TypeInitializationState = 'Invalid' | 'Identifiable' | 'Completed';
 
@@ -57,7 +61,7 @@ export abstract class Type {
      * Identifiers might have a naming schema for calculatable values.
      */
     getIdentifier(): string {
-        this.assertStateOrLater('Identifiable');
+        // an Identifier must be available; note that the state might be 'Invalid' nevertheless, which is required to handle cyclic type definitions
         assertTrue(this.identifier !== undefined);
         return this.identifier;
     }
@@ -130,20 +134,20 @@ export abstract class Type {
 
     protected stateListeners: TypeStateListener[] = [];
 
-    addListener(listener: TypeStateListener, informIfNotInvalidAnymore: boolean): void {
-        this.stateListeners.push(listener);
+    addListener(newListeners: TypeStateListener, informIfNotInvalidAnymore: boolean): void {
+        this.stateListeners.push(newListeners);
         if (informIfNotInvalidAnymore) {
             const currentState = this.getInitializationState();
             switch (currentState) {
                 case 'Invalid':
                     // don't inform about the Invalid state!
                     break;
                 case 'Identifiable':
-                    listener.switchedToIdentifiable(this);
+                    newListeners.switchedToIdentifiable(this);
                     break;
                 case 'Completed':
-                    listener.switchedToIdentifiable(this); // inform about both Identifiable and Completed!
-                    listener.switchedToCompleted(this);
+                    newListeners.switchedToIdentifiable(this); // inform about both Identifiable and Completed!
+                    newListeners.switchedToCompleted(this);
                     break;
                 default:
                     assertUnreachable(currentState);
@@ -197,21 +201,18 @@ export abstract class Type {
         this.onCompletion = preconditions.onCompleted ?? (() => {});
         this.onInvalidation = preconditions.onInvalidated ?? (() => {});
 
-        if (this.kind.$name === 'ClassKind') {
-            console.log('');
-        }
         // preconditions for Identifiable
         this.waitForIdentifiable = new WaitingForIdentifiableAndCompletedTypeReferences(
             preconditions.preconditionsForIdentifiable?.referencesToBeIdentifiable,
             preconditions.preconditionsForIdentifiable?.referencesToBeCompleted,
         );
-        this.waitForIdentifiable.addTypesToIgnoreForCycles(new Set([this]));
+        this.waitForIdentifiable.addTypesToIgnoreForCycles(new Set([this])); // start of the principle: children don't need to wait for their parents
         // preconditions for Completed
         this.waitForCompleted = new WaitingForIdentifiableAndCompletedTypeReferences(
             preconditions.preconditionsForCompleted?.referencesToBeIdentifiable,
             preconditions.preconditionsForCompleted?.referencesToBeCompleted,
         );
-        this.waitForCompleted.addTypesToIgnoreForCycles(new Set([this]));
+        this.waitForCompleted.addTypesToIgnoreForCycles(new Set([this])); // start of the principle: children don't need to wait for their parents
         // preconditions for Invalid
         this.waitForInvalid = new WaitingForInvalidTypeReferences(
             preconditions.referencesRelevantForInvalidation ?? [],
@@ -262,7 +263,7 @@ export abstract class Type {
         this.waitForCompleted.addTypesToIgnoreForCycles(additionalTypesToIgnore);
     }
 
-    deconstruct(): void {
+    dispose(): void {
         // clear everything
         this.stateListeners.splice(0, this.stateListeners.length);
         this.waitForInvalid.getWaitForRefsInvalid().forEach(ref => ref.deconstruct());

packages/typir/src/kinds/class-kind.ts

@@ -30,7 +30,9 @@ export class ClassType extends Type {
     protected methods: MethodDetails[]; // unordered
 
     constructor(kind: ClassKind, typeDetails: ClassTypeDetails) {
-        super(undefined);
+        super(kind.options.typing === 'Nominal'
+            ? kind.calculateNominalIdentifier(typeDetails) // use the name of the class as identifier already now
+            : undefined); // the identifier for structurally typed classes will be set later after resolving all fields and methods
         this.kind = kind;
         this.className = typeDetails.className;
 
@@ -388,6 +390,12 @@ export interface CreateFieldDetails {
     type: TypeSelector;
 }
 
+/**
+ * Describes all properties of Methods of a Class.
+ * The final reason to describe methods with Function types was to have a simple solution and to reuse all the implementations for functions,
+ * since methods and functions are the same from a typing perspective.
+ * This interfaces makes annotating further properties to methods easier (which are not supported by functions).
+ */
 export interface MethodDetails {
     type: TypeReference<FunctionType>;
     // methods might have some more properties in the future
@@ -444,8 +452,6 @@ export class ClassKind implements Kind {
         assertTrue(this.options.maximumNumberOfSuperClasses >= 0); // no negative values
     }
 
-    // zwei verschiedene Use cases für Calls: Reference/use (e.g. Var-Type) VS Creation (e.g. Class-Declaration)
-
     /**
      * For the use case, that a type is used/referenced, e.g. to specify the type of a variable declaration.
      * @param typeDetails all information needed to identify the class
@@ -523,6 +529,10 @@ export class ClassKind implements Kind {
         }
     }
 
+    calculateNominalIdentifier<T>(typeDetails: ClassTypeDetails<T>): string {
+        return this.getIdentifierPrefix() + typeDetails.className;
+    }
+
     getMethodKind(): FunctionKind {
         // ensure, that Typir uses the predefined 'function' kind for methods
         const kind = this.services.kinds.get(FunctionKindName);
@@ -546,7 +556,6 @@ export function isClassKind(kind: unknown): kind is ClassKind {
 }
 
 
-// TODO Review: Is it better to not have "extends TypeInitializer" and to merge TypeInitializer+ClassTypeInitializer into one class?
 export class ClassTypeInitializer<T = unknown, T1 = unknown, T2 = unknown> extends TypeInitializer<ClassType> implements TypeStateListener {
     protected readonly typeDetails: CreateClassTypeDetails<T, T1, T2>;
     protected readonly kind: ClassKind;
@@ -562,7 +571,7 @@ export class ClassTypeInitializer<T = unknown, T1 = unknown, T2 = unknown> exten
         this.initialClassType = new ClassType(kind, typeDetails as CreateClassTypeDetails);
         if (kind.options.typing === 'Structural') {
             // register structural classes also by their names, since these names are usually used for reference in the DSL/AST!
-            this.services.graph.addNode(this.initialClassType, kind.getIdentifierPrefix() + typeDetails.className);
+            this.services.graph.addNode(this.initialClassType, kind.calculateNominalIdentifier(typeDetails));
         }
 
         this.inferenceRules = createInferenceRules<T, T1, T2>(this.typeDetails, this.kind, this.initialClassType);
@@ -588,8 +597,9 @@ export class ClassTypeInitializer<T = unknown, T1 = unknown, T2 = unknown> exten
 
             if (this.kind.options.typing === 'Structural') {
                 // replace the type in the type graph
-                this.services.graph.removeNode(classType, this.kind.getIdentifierPrefix() + this.typeDetails.className);
-                this.services.graph.addNode(readyClassType, this.kind.getIdentifierPrefix() + this.typeDetails.className);
+                const nominalIdentifier = this.kind.calculateNominalIdentifier(this.typeDetails);
+                this.services.graph.removeNode(classType, nominalIdentifier);
+                this.services.graph.addNode(readyClassType, nominalIdentifier);
             }
 
             // remove the inference rules for the invalid type
@@ -613,7 +623,7 @@ export class ClassTypeInitializer<T = unknown, T1 = unknown, T2 = unknown> exten
         if (this.typeDetails.inferenceRuleForDeclaration === null) {
             // check for cycles in sub-type-relationships of classes
             if ((classType as ClassType).hasSubSuperClassCycles()) {
-                throw new Error(`Circles in super-sub-class-relationships are not allowed: ${classType.getName()}`);
+                throw new Error(`Cycles in super-sub-class-relationships are not allowed: ${classType.getName()}`);
             }
         }
 
@@ -622,7 +632,7 @@ export class ClassTypeInitializer<T = unknown, T1 = unknown, T2 = unknown> exten
     }
 
     switchedToInvalid(_previousClassType: Type): void {
-        // do nothing
+        // nothing specific needs to be done for Classes here, since the base implementation takes already care about all relevant stuff
     }
 
     override getTypeInitial(): ClassType {
@@ -919,7 +929,7 @@ export function createNoSuperClassCyclesValidation(isRelevant: (domainElement: u
                         $problem: ValidationProblem,
                         domainElement,
                         severity: 'error',
-                        message: `Circles in super-sub-class-relationships are not allowed: ${classType.getName()}`,
+                        message: `Cycles in super-sub-class-relationships are not allowed: ${classType.getName()}`,
                     });
                 }
             }

packages/typir/src/kinds/function-kind.ts

@@ -609,7 +609,7 @@ export class FunctionTypeInitializer<T> extends TypeInitializer<FunctionType> im
     }
 
     switchedToInvalid(_functionType: Type): void {
-        // empty
+        // nothing specific needs to be done for Functions here, since the base implementation takes already care about all relevant stuff
     }
 }
 

packages/typir/src/utils/test-utils.ts

@@ -8,6 +8,15 @@ import { expect } from 'vitest';
 import { Type } from '../graph/type-node.js';
 import { TypirServices } from '../typir.js';
 
+/**
+ * Testing utility to check, that exactly the expected types are in the type system.
+ * @param services the Typir services
+ * @param filterTypes used to identify the types of interest
+ * @param namesOfExpectedTypes the names (not the identifiers!) of the expected types;
+ * ensures that there are no more types;
+ * it is possible to specify names multiple times, if there are multiple types with the same name (e.g. for overloaded functions)
+ * @returns all the found types
+ */
 export function expectTypirTypes(services: TypirServices, filterTypes: (type: Type) => boolean, ...namesOfExpectedTypes: string[]): Type[] {
     const types = services.graph.getAllRegisteredTypes().filter(filterTypes);
     types.forEach(type => expect(type.getInitializationState()).toBe('Completed')); // check that all types are 'Completed'
@@ -18,6 +27,6 @@ export function expectTypirTypes(services: TypirServices, filterTypes: (type: Ty
         expect(index >= 0).toBeTruthy();
         typeNames.splice(index, 1); // removing elements is needed to work correctly with duplicated entries
     }
-    expect(typeNames).toHaveLength(0);
+    expect(typeNames, `There are more types than expected: ${typeNames.join(', ')}`).toHaveLength(0);
     return types;
 }

packages/typir/src/utils/type-initialization.ts

@@ -21,6 +21,10 @@ export type TypeInitializerListener<T extends Type = Type> = (type: T) => void;
  * Since the first Typir type is not yet in the type systems (since it still waits for B) and therefore remains unknown,
  * it will be tried to create A a second time, again delayed, since B is still not yet available.
  * When B is created, A is waiting twice and might be created twice, if no TypeInitializer is used.
+ *
+ * Design decision: While this class does not provide some many default implementations,
+ * a common super class (or interface) of all type initializers is useful,
+ * since they all can be used as TypeSelector in an easy way.
  */
 export abstract class TypeInitializer<T extends Type = Type> {
     protected readonly services: TypirServices;
@@ -40,7 +44,7 @@ export abstract class TypeInitializer<T extends Type = Type> {
         if (existingType) {
             // ensure, that the same type is not duplicated!
             this.typeToReturn = existingType as T;
-            newType.deconstruct();
+            newType.dispose();
         } else {
             this.typeToReturn = newType;
             this.services.graph.addNode(this.typeToReturn);
@@ -54,7 +58,7 @@ export abstract class TypeInitializer<T extends Type = Type> {
         return this.typeToReturn;
     }
 
-    // TODO using this type feels wrong, but otherwise, it seems not to work ...
+    // TODO using this type feels wrong, but without this approach, it seems not to work ...
     abstract getTypeInitial(): T
 
     getTypeFinal(): T | undefined {

packages/typir/src/utils/utils-definitions.ts

@@ -123,6 +123,11 @@ export class WaitingForIdentifiableAndCompletedTypeReferences<T extends Type = T
         }
     }
 
+    /**
+     * This method is called to inform about additional types which can be ignored during the waiting/resolving process.
+     * This helps to deal with cycles in type dependencies.
+     * @param moreTypesToIgnore might contain duplicates, which are filtered internally
+     */
     addTypesToIgnoreForCycles(moreTypesToIgnore: Set<Type>): void {
         // identify the actual new types to ignore (filtering out the types which are already ignored)
         const newTypesToIgnore: Set<Type> = new Set();
@@ -164,7 +169,7 @@ export class WaitingForIdentifiableAndCompletedTypeReferences<T extends Type = T
     }
 
     onTypeReferenceResolved(_reference: TypeReference<Type>, resolvedType: Type): void {
-        // inform the referenced type about the types to ignore for completion
+        // inform the referenced type about the types to ignore for completion, so that the type could switch to its next phase (if needed)
         resolvedType.ignoreDependingTypesDuringInitialization(this.typesToIgnoreForCycles);
         resolvedType.addListener(this, false);
         // check, whether all TypeReferences are resolved and the resolved types are in the expected state