Support Literal Unions (#50)

* Enhance attribute parsing to handle mixed literal union types

- Updated `getType` function to identify mixed literal unions and return an `isMixedUnion` flag.
- Modified `getNodeAsAttribute` to raise errors for unsupported mixed literal union types.
- Added tests for both valid and invalid mixed literal unions to ensure proper error handling.
- Introduced new fixture files for testing mixed literal unions.

* Update src/parsers/attribute-parser.js

Co-authored-by: Copilot <[email protected]>

* Fix test execution by uncommenting the call to runTests for enum.valid.js

* Refactor attribute parser error message and enhance mixed union detection

- Updated error message formatting in `attribute-parser.js` for clarity.
- Improved logic in `getType` function in `ts-utils.js` to accurately identify mixed literal unions.

---------

Co-authored-by: Copilot <[email protected]>

Author: marklundin

src/parsers/attribute-parser.js

@@ -89,10 +89,22 @@ export class AttributeParser {
     getNodeAsAttribute(node, errors = []) {
 
         const name = node.name && ts.isIdentifier(node.name) && node.name.text;
-        const { type, name: typeName, array } = getType(node, this.typeChecker);
+        const { type, name: typeName, array, isMixedUnion } = getType(node, this.typeChecker);
+
         const enums = this.getEnumMembers(node, errors);
         let value = null;
 
+        // If this is not an enum and the type is a mixed union, ie 'a' | false | 1,
+        // we need to raise an error as this is not a supported attribute type
+        if (isMixedUnion && enums.length === 0) {
+            errors.push(new ParsingError(
+                node,
+                `Mixed literal union types (combining different primitive types like string | number) are not supported for attribute: '${name}'. ` +
+                'Please use a union of the same primitive type (e.g., \'1 | 2 | 3\' or \'"a" | "b" | "c"\') or refactor your type.'
+            ));
+            return;
+        }
+
         // we don't need to serialize the value for arrays
         const serializer = !array && this.typeSerializerMap.get(typeName);
         if (serializer) {

src/utils/ts-utils.js

@@ -321,9 +321,23 @@ export function getType(node, typeChecker) {
         const type = typeChecker.getTypeAtLocation(node);
         const array = typeChecker.isArrayType(type);
         const actualType = array ? typeChecker.getElementTypeOfArrayType(type) : type;
-        const name = getPrimitiveEnumType(actualType, typeChecker) ?? typeChecker.typeToString(actualType);
 
-        return { type: actualType, name, array };
+        // A type could be a literal union, such as '1 | 2 | 3', so we need to get the base type
+        const baseType = typeChecker.getBaseTypeOfLiteralType(actualType);
+
+        // If baseType has multiple types, it means we have a mixed union, ie 'a' | false | 1.
+        let isMixedUnion = false;
+        if (Array.isArray(baseType.types)) {
+            const primitiveKinds = new Set(
+                baseType.types.map(t => typeChecker.getBaseTypeOfLiteralType(t))
+            );
+            primitiveKinds.delete(null);
+            isMixedUnion = primitiveKinds.size > 1;
+        }
+
+        const name = getPrimitiveEnumType(baseType, typeChecker) ?? typeChecker.typeToString(baseType);
+
+        return { type: baseType, name, array, isMixedUnion };
     }
 
     return null;

test/fixtures/literal-unions.invalid.js

@@ -0,0 +1,23 @@
+import { Script } from 'playcanvas';
+
+class Example extends Script {
+    /**
+     * @attribute
+     * @type {1 | 'one' | true}
+     */
+    mixedLiteralUnion;
+
+    /**
+     * @attribute
+     * @type {'a' | 1 | false}
+     */
+    mixedStringNumberBoolean;
+
+    /**
+     * @attribute
+     * @type {string | number | boolean}
+     */
+    mixedPrimitiveTypes;
+}
+
+export { Example };

test/fixtures/literal-unions.valid.js

@@ -0,0 +1,23 @@
+import { Script } from 'playcanvas';
+
+class Example extends Script {
+    /**
+     * @attribute
+     * @type {'a' | 'b' | 'c'}
+     */
+    stringUnion;
+
+    /**
+     * @attribute
+     * @type {1 | 2 | 3}
+     */
+    numericUnion;
+
+    /**
+     * @attribute
+     * @type {true | false}
+     */
+    booleanUnion;
+}
+
+export { Example };

test/tests/invalid/literal-unions.test.js

@@ -0,0 +1,42 @@
+import { expect } from 'chai';
+import { describe, it, before } from 'mocha';
+
+import { parseAttributes } from '../../utils.js';
+
+describe('INVALID: Mixed literal union types', function () {
+    let data;
+    before(async function () {
+        data = await parseAttributes('./literal-unions.invalid.js');
+    });
+
+    it('should have errors for mixed literal unions', function () {
+        expect(data).to.exist;
+        expect(data[0].example).to.exist;
+        expect(data[1]).to.be.empty;
+        expect(data[0].example.errors).to.not.be.empty; // errors array should not be empty
+    });
+
+    it('mixedLiteralUnion: should raise an error for mixed literal union', function () {
+        const errors = data[0].example.errors;
+        const mixedUnionError = errors.find(error => error.message.includes('mixedLiteralUnion') ||
+            error.message.includes('mixed literal union')
+        );
+        expect(mixedUnionError).to.exist;
+    });
+
+    it('mixedStringNumberBoolean: should raise an error for mixed string/number/boolean union', function () {
+        const errors = data[0].example.errors;
+        const mixedUnionError = errors.find(error => error.message.includes('mixedStringNumberBoolean') ||
+            error.message.includes('mixed literal union')
+        );
+        expect(mixedUnionError).to.exist;
+    });
+
+    it('mixedPrimitiveTypes: should raise an error for mixed primitive types union', function () {
+        const errors = data[0].example.errors;
+        const mixedUnionError = errors.find(error => error.message.includes('mixedPrimitiveTypes') ||
+            error.message.includes('mixed literal union')
+        );
+        expect(mixedUnionError).to.exist;
+    });
+});

test/tests/valid/literal-unions.test.js

@@ -0,0 +1,44 @@
+import { expect } from 'chai';
+import { describe, it, before } from 'mocha';
+
+import { parseAttributes } from '../../utils.js';
+
+describe('VALID: Literal union types', function () {
+    let data;
+    before(async function () {
+        data = await parseAttributes('./literal-unions.valid.js');
+    });
+
+    it('only results should exist', function () {
+        expect(data).to.exist;
+        expect(data[0]).to.not.be.empty;
+        expect(data[1]).to.be.empty;
+    });
+
+    it('Example: should exist without errors', function () {
+        expect(data[0]?.example).to.exist;
+        expect(data[0].example.attributes).to.not.be.empty;
+        expect(data[0].example.errors).to.be.empty;
+    });
+
+    it('stringUnion: should be a string attribute from literal union', function () {
+        expect(data[0].example.attributes.stringUnion).to.exist;
+        expect(data[0].example.attributes.stringUnion.name).to.equal('stringUnion');
+        expect(data[0].example.attributes.stringUnion.type).to.equal('string');
+        expect(data[0].example.attributes.stringUnion.array).to.equal(false);
+    });
+
+    it('numericUnion: should be a number attribute from literal union', function () {
+        expect(data[0].example.attributes.numericUnion).to.exist;
+        expect(data[0].example.attributes.numericUnion.name).to.equal('numericUnion');
+        expect(data[0].example.attributes.numericUnion.type).to.equal('number');
+        expect(data[0].example.attributes.numericUnion.array).to.equal(false);
+    });
+
+    it('booleanUnion: should be a boolean attribute from literal union', function () {
+        expect(data[0].example.attributes.booleanUnion).to.exist;
+        expect(data[0].example.attributes.booleanUnion.name).to.equal('booleanUnion');
+        expect(data[0].example.attributes.booleanUnion.type).to.equal('boolean');
+        expect(data[0].example.attributes.booleanUnion.array).to.equal(false);
+    });
+});