fix: stop or() union constructor from stripping branding (#88)

BREAKING CHANGE: union types built with the `.or()` constructor are now
possibly stricter as the branding is not unintentionally stripped anymore.

Author: untio11

etc/types.api.md

@@ -69,7 +69,7 @@ export abstract class BaseTypeImpl<ResultType, TypeConfig = unknown> implements
     literal(input: DeepUnbranded<ResultType>): ResultType;
     maybeStringify(value: ResultType): string | undefined;
     abstract readonly name: string;
-    or<Other>(_other: BaseTypeImpl<Other, any>): Type<ResultType | Other>;
+    or<Other extends BaseTypeImpl<unknown>>(_other: Other): Type<ResultType | TypeOf<Other>>;
     stringify(value: ResultType): string;
     abstract readonly typeConfig: TypeConfig;
     protected typeParser?(input: unknown, options: ValidationOptions): Result<unknown>;

markdown/types.basetypeimpl.or.md

@@ -9,18 +9,18 @@ Union this Type with another Type.
 **Signature:**
 
 ```typescript
-or<Other>(_other: BaseTypeImpl<Other, any>): Type<ResultType | Other>;
+or<Other extends BaseTypeImpl<unknown>>(_other: Other): Type<ResultType | TypeOf<Other>>;
 ```
 
 ## Parameters
 
-| Parameter | Type                                                              | Description |
-| --------- | ----------------------------------------------------------------- | ----------- |
-| \_other   | [BaseTypeImpl](./types.basetypeimpl.md)<!-- -->&lt;Other, any&gt; |             |
+| Parameter | Type  | Description |
+| --------- | ----- | ----------- |
+| \_other   | Other |             |
 
 **Returns:**
 
-[Type](./types.type.md)<!-- -->&lt;ResultType \| Other&gt;
+[Type](./types.type.md)<!-- -->&lt;ResultType \| [TypeOf](./types.typeof.md)<!-- -->&lt;Other&gt;&gt;
 
 ## Remarks
 

src/base-type.ts

@@ -13,6 +13,7 @@ import type {
     Type,
     TypeImpl,
     TypeLink,
+    TypeOf,
     TypeguardFor,
     TypeguardResult,
     ValidationOptions,
@@ -457,7 +458,7 @@ export abstract class BaseTypeImpl<ResultType, TypeConfig = unknown> implements
      * See {@link UnionType} for more information about unions.
      */
     // istanbul ignore next: using ordinary stub instead of module augmentation to lighten the load on the TypeScript compiler
-    or<Other>(_other: BaseTypeImpl<Other, any>): Type<ResultType | Other> {
+    or<Other extends BaseTypeImpl<unknown>>(_other: Other): Type<ResultType | TypeOf<Other>> {
         throw new Error('stub');
     }
 

src/types/union.test.ts

@@ -1,5 +1,5 @@
 import type { DeepUnbranded, The } from '../interfaces';
-import { createExample, defaultUsualSuspects, testTypeImpl } from '../testutils';
+import { assignableTo, createExample, defaultUsualSuspects, testTypeImpl } from '../testutils';
 import { boolean } from './boolean';
 import { object, partial } from './interface';
 import { keyof } from './keyof';
@@ -493,3 +493,24 @@ testTypeImpl({
         ],
     ],
 });
+
+const BrandedA = literal('A').withBrand('BrandA');
+const BrandedB = literal('B').withBrand('BrandB');
+
+type BrandedUnion = The<typeof BrandedUnion>;
+const BrandedUnion = union('BrandedUnion', [BrandedA, BrandedB]);
+
+type BrandedOr1 = The<typeof BrandedOr1>;
+const BrandedOr1 = BrandedA.or(BrandedB);
+
+type BrandedOr2 = The<typeof BrandedOr2>;
+const BrandedOr2 = BrandedB.or(BrandedA);
+test('equivalence between `union()` and `.or()`', () => {
+    // Validating issue #87
+    assignableTo<BrandedUnion>(BrandedOr1.literal('A'));
+    assignableTo<BrandedUnion>(BrandedOr2.literal('A'));
+    assignableTo<BrandedOr1>(BrandedUnion.literal('A'));
+    assignableTo<BrandedOr2>(BrandedUnion.literal('A'));
+    // @ts-expect-error Unbranded literal not assignable to branded literal union type
+    assignableTo<BrandedOr1>('B');
+});