Fix optional and undefined properties for custom types (#94)

This PR improves the handling of optional properties for custom types:
- It fixes a bug when assigning `undefined` in explicit way to optional properties.
- It fixes another bug when comparing optional custom properties for equality.
- It enables to define properties for custom types using `undefined` in explicit way.

Author: JohannesMeierSE

CHANGELOG.md

@@ -5,6 +5,22 @@ Note that the versions "0.x.0" probably will include breaking changes.
 For each minor and major version, there is a corresponding [milestone on GitHub](https://github.com/TypeFox/typir/milestones).
 
 
+## v0.4.0 (2025-??-??)
+
+[Linked issues and PRs for v0.4.0](https://github.com/TypeFox/typir/milestone/5)
+
+### New features
+
+- The TypeScript type of properties for custom types might use `undefined` now.
+
+### Breaking changes
+
+### Fixed bugs
+
+- Initializing optional properties of custom types with `undefined` failed, as reported in [#77](https://github.com/TypeFox/typir/discussions/77#discussioncomment-14149139).
+- When checking the equality of custom types, the values for the same property might have different TypeScript types, since optional propeties might be set to `undefined`.
+
+
 ## v0.3.0 (2025-08-15)
 
 [Linked issues and PRs for v0.3.0](https://github.com/TypeFox/typir/milestone/4)

documentation/kinds/custom-types.md

@@ -67,8 +67,9 @@ This sections describes the features of custom types in more detail.
 
 ### Custom properties
 
-Custom types have custom properties ("data") including primitive values, Typir types and nesting/grouping with sets, arrays, and maps, and recursion.
+Custom types have custom properties ("data") including primitive values and `undefined`, Typir types and nesting/grouping with sets, arrays, and maps, and recursion.
 See `custom-nested-properties.test.ts` for some examples.
+It is also possible to mark properties as optional with the `?` operator (see `custom-optional-properties.test.ts` for an example).
 When the initialization of the custom type is done, all its properties are read-only.
 
 ### Support by the TypeScript compiler

packages/typir/src/kinds/custom/custom-definitions.ts

@@ -21,6 +21,7 @@ export type CustomTypeProperties = {
 export type CustomTypePropertyTypes =
     | Type
     | string | number | boolean | bigint | symbol
+    | undefined // to make properties optional
     | CustomTypePropertyTypes[] | Map<string, CustomTypePropertyTypes> | Set<CustomTypePropertyTypes>
     | CustomTypeProperties // recursive nesting
     ;
@@ -42,6 +43,7 @@ export type CustomTypePropertyInitialization<T extends CustomTypePropertyTypes,
     T extends Type ? TypeDescriptorForCustomTypes<T, Specifics> :
     // unchanged for the atomic cases:
     T extends (string | number | boolean | bigint | symbol) ? T :
+    T extends undefined ? T :
     // ... in recursive way for the composites:
     T extends Array<infer ValueType> ? (ValueType extends CustomTypePropertyTypes ? Array<CustomTypePropertyInitialization<ValueType, Specifics>> : never) :
     T extends Map<string, infer ValueType> ? (ValueType extends CustomTypePropertyTypes ? Map<string, CustomTypePropertyInitialization<ValueType, Specifics>> : never) :
@@ -61,6 +63,7 @@ export type CustomTypePropertyStorage<T extends CustomTypePropertyTypes, Specifi
     T extends Type ? TypeReference<T, Specifics> :
     // unchanged for the atomic cases:
     T extends (string | number | boolean | bigint | symbol) ? T :
+    T extends undefined ? T :
     // ... in recursive way for the composites:
     T extends Array<infer ValueType> ? (ValueType extends CustomTypePropertyTypes ? ReadonlyArray<CustomTypePropertyStorage<ValueType, Specifics>> : never) :
     T extends Map<string, infer ValueType> ? (ValueType extends CustomTypePropertyTypes ? ReadonlyMap<string, CustomTypePropertyStorage<ValueType, Specifics>> : never) :

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

@@ -137,12 +137,14 @@ export class CustomKind<Properties extends CustomTypeProperties, Specifics exten
         // primitives
         else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol') {
             return String(value);
+        } else if (value === undefined) { // required for optional properties
+            return 'undefined';
         }
         // composite with recursive object / index signature
         else if (typeof value === 'object' && value !== null) {
             return this.calculateIdentifierAll(value as CustomTypeInitialization<Properties, Specifics>);
         } else {
-            throw new Error(`missing implementation for ${value}`);
+            throw new Error(`missing implementation for '${value}'`);
         }
     }
 }

packages/typir/src/kinds/custom/custom-type.ts

@@ -105,12 +105,14 @@ export class CustomType<Properties extends CustomTypeProperties, Specifics exten
         // primitives
         else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol') {
             return value as unknown as CustomTypePropertyStorage<T, Specifics>;
+        } else if (value === undefined) { // required for optional properties
+            return undefined as unknown as CustomTypePropertyStorage<T, Specifics>;
         }
         // composite with recursive object / index signature
         else if (typeof value === 'object' && value !== null) {
             return this.replaceAllProperties(value as CustomTypeInitialization<CustomTypeProperties, Specifics>, collectedReferences) as CustomTypePropertyStorage<T, Specifics>;
         } else {
-            throw new Error(`missing implementation for ${value}`);
+            throw new Error(`missing implementation for '${value}'`);
         }
     }
 
@@ -167,7 +169,14 @@ export class CustomType<Properties extends CustomTypeProperties, Specifics exten
         return result;
     }
     protected analyzeTypeEqualityProblemsSingle<T extends CustomTypePropertyTypes>(value1: CustomTypePropertyStorage<T, Specifics>, value2: CustomTypePropertyStorage<T, Specifics>): TypirProblem[] {
-        assertTrue(typeof value1 === typeof value2);
+        if (typeof value1 !== typeof value2) {
+            // this case might occur for optional properties, since `undefined` is a different TypeScript type than a non-undefined value
+            return [<ValueConflict>{
+                $problem: ValueConflict,
+                firstValue: `'${String(value1)}' has the TypeScript type ${typeof value1}`,
+                secondValue: `'${String(value2)}' has the TypeScript type ${typeof value2}`,
+            }];
+        }
         // a type is stored in a TypeReference!
         if (value1 instanceof TypeReference) {
             return checkTypes(value1.getType(), (value2 as TypeReference<Type, Specifics>).getType(), createTypeCheckStrategy('EQUAL_TYPE', this.kind.services), false);
@@ -226,6 +235,8 @@ export class CustomType<Properties extends CustomTypeProperties, Specifics exten
         // primitives
         else if (typeof value1 === 'string' || typeof value1 === 'number' || typeof value1 === 'boolean' || typeof value1 === 'bigint' || typeof value1 === 'symbol') {
             return checkValueForConflict(value1, value2, 'value');
+        } else if (value1 === undefined) { // required for optional properties
+            return checkValueForConflict(value1, value2, 'value');
         }
         // composite with recursive object / index signature
         else if (typeof value1 === 'object' && value1 !== null) {

packages/typir/test/kinds/custom/custom-optional-properties.test.ts

@@ -0,0 +1,82 @@
+/******************************************************************************
+ * Copyright 2025 TypeFox GmbH
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License, which is available in the project root.
+ ******************************************************************************/
+
+import { beforeEach, describe, expect, test } from 'vitest';
+import { CustomKind } from '../../../src/kinds/custom/custom-kind.js';
+import { TestingSpecifics, createTypirServicesForTesting } from '../../../src/test/predefined-language-nodes.js';
+import { TypirServices } from '../../../src/typir.js';
+
+// These test cases test custom types with optional properties
+
+describe('Optional custom properties', () => {
+    type MyCustomType = {
+        myNumber?: number;
+        myString?: string;
+    };
+
+    let typir: TypirServices<TestingSpecifics>;
+    let customKind: CustomKind<MyCustomType, TestingSpecifics>;
+
+    beforeEach(() => {
+        typir = createTypirServicesForTesting();
+
+        customKind = new CustomKind<MyCustomType, TestingSpecifics>(typir, {
+            name: 'MyCustom1',
+            calculateTypeName: properties => `Custom1-${properties.myNumber}-${properties.myString}`,
+        });
+    });
+
+    test('Specified non-undefined values', () => {
+        const properties = customKind.create({ properties: { myNumber: 123, myString: 'hello' } }).finish().getTypeFinal()!.properties;
+        expect(properties.myNumber).toBe(123);
+        expect(properties.myString).toBe('hello');
+    });
+
+    test('Skipped all values (implicit undefined)', () => {
+        const properties = customKind.create({ properties: { /* empty */ } }).finish().getTypeFinal()!.properties;
+        expect(properties.myNumber).toBe(undefined);
+        expect(properties.myString).toBe(undefined);
+    });
+
+    test('Used "undefined" as values (explicit undefined)', () => {
+        const properties = customKind.create({ properties: { myNumber: undefined, myString: undefined } }).finish().getTypeFinal()!.properties;
+        expect(properties.myNumber).toBe(undefined);
+        expect(properties.myString).toBe(undefined);
+    });
+
+});
+
+describe('Custom properties with "undefined" as type', () => {
+    type MyCustomType = {
+        myNumber: number | undefined;
+        myString: string | undefined;
+    };
+
+    let typir: TypirServices<TestingSpecifics>;
+    let customKind: CustomKind<MyCustomType, TestingSpecifics>;
+
+    beforeEach(() => {
+        typir = createTypirServicesForTesting();
+
+        customKind = new CustomKind<MyCustomType, TestingSpecifics>(typir, {
+            name: 'MyCustom1',
+            calculateTypeName: properties => `Custom1-${properties.myNumber}-${properties.myString}`,
+        });
+    });
+
+    test('Specified non-undefined values', () => {
+        const properties = customKind.create({ properties: { myNumber: 123, myString: 'hello' } }).finish().getTypeFinal()!.properties;
+        expect(properties.myNumber).toBe(123);
+        expect(properties.myString).toBe('hello');
+    });
+
+    test('Used "undefined" as values (explicit undefined)', () => {
+        const properties = customKind.create({ properties: { myNumber: undefined, myString: undefined } }).finish().getTypeFinal()!.properties;
+        expect(properties.myNumber).toBe(undefined);
+        expect(properties.myString).toBe(undefined);
+    });
+
+});