feat(types): prefer MemberOfUnion, retain deprecated LastOfUnion (CORE-26)

.changeset/quiet-union-member.md

@@ -0,0 +1,6 @@
+---
+"@ylfjuk-core/types": patch
+"@ylfjuk/core": patch
+---
+
+Add `MemberOfUnion` as the preferred name for selecting a single union member with unspecified, compiler-dependent selection. Deprecate `LastOfUnion` while retaining it as a compatible alias with unchanged behavior.

packages/core/tests/member-of-union.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expectTypeOf, it } from "vitest";
+
+import type { MemberOfUnion as TypesMemberOfUnion } from "@ylfjuk-core/types";
+import type { LastOfUnion, MemberOfUnion, UnionToTuple } from "@ylfjuk/core";
+
+describe("union type exports", () => {
+	it("exposes the preferred name and compatibility alias through core", () => {
+		type Input = 1 | 2 | 3 | "bob";
+
+		expectTypeOf<MemberOfUnion<Input>>().toEqualTypeOf<TypesMemberOfUnion<Input>>();
+		expectTypeOf<LastOfUnion<Input>>().toEqualTypeOf<MemberOfUnion<Input>>();
+		expectTypeOf<MemberOfUnion<"bob">>().toEqualTypeOf<"bob">();
+		expectTypeOf<MemberOfUnion<never>>().toBeNever();
+		expectTypeOf<LastOfUnion<never>>().toBeNever();
+		expectTypeOf<UnionToTuple<Input>[number]>().toEqualTypeOf<Input>();
+		expectTypeOf<UnionToTuple<Input>["length"]>().toEqualTypeOf<4>();
+	});
+});

packages/types/__tests__/last-of-union.spec.ts

@@ -1,12 +1,18 @@
 import { describe, expectTypeOf, it } from "vitest";
 
-import type { LastOfUnion } from "../src/last-of-union";
+import type { LastOfUnion, MemberOfUnion } from "@ylfjuk-core/types";
+
+import type { LastOfUnion as LegacyPath } from "../src/last-of-union.js";
 
 describe("LastOfUnion", () => {
-	it("should extract the last element in a union", () => {
-		type Actual = LastOfUnion<1 | 2 | 3 | 4 | 5 | "bob" | 6>;
-		type Expected = 6;
+	it("retains the public alias and existing source import path", () => {
+		type Input = 1 | 2 | 3 | "bob";
 
-		expectTypeOf<Actual>().toEqualTypeOf<Expected>();
+		expectTypeOf<LastOfUnion<Input>>().toEqualTypeOf<MemberOfUnion<Input>>();
+		expectTypeOf<LegacyPath<Input>>().toEqualTypeOf<MemberOfUnion<Input>>();
+		expectTypeOf<LastOfUnion<"bob">>().toEqualTypeOf<"bob">();
+		expectTypeOf<LastOfUnion<never>>().toBeNever();
+		expectTypeOf<LastOfUnion<boolean>>().toEqualTypeOf<MemberOfUnion<boolean>>();
+		expectTypeOf<LastOfUnion<string | "bob">>().toEqualTypeOf<string>();
 	});
 });

packages/types/__tests__/member-of-union.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expectTypeOf, it } from "vitest";
+
+import type { IsDisjointUnion, MemberOfUnion } from "@ylfjuk-core/types";
+
+describe("MemberOfUnion", () => {
+	it("selects exactly one member without assuming union order", () => {
+		type Input = 1 | 2 | 3 | "bob";
+		type Actual = MemberOfUnion<Input>;
+
+		expectTypeOf<Actual>().not.toBeNever();
+		expectTypeOf<Actual>().toExtend<Input>();
+		expectTypeOf<IsDisjointUnion<Actual>>().toEqualTypeOf<false>();
+	});
+
+	it("preserves a singleton", () => {
+		expectTypeOf<MemberOfUnion<"bob">>().toEqualTypeOf<"bob">();
+	});
+
+	it("returns never for an empty union", () => {
+		expectTypeOf<MemberOfUnion<never>>().toBeNever();
+	});
+
+	it("selects one boolean literal", () => {
+		type Actual = MemberOfUnion<boolean>;
+
+		expectTypeOf<Actual>().not.toBeNever();
+		expectTypeOf<IsDisjointUnion<Actual>>().toEqualTypeOf<false>();
+	});
+
+	it("respects a union collapsed by the compiler", () => {
+		expectTypeOf<MemberOfUnion<string | "bob">>().toEqualTypeOf<string>();
+	});
+});

packages/types/__tests__/union-to-tuple.spec.ts

@@ -1,12 +1,18 @@
 import { describe, expectTypeOf, it } from "vitest";
 
-import type { UnionToTuple } from "../src/union-to-tuple";
+import type { UnionToTuple } from "../src/union-to-tuple.js";
 
 describe("UnionToTuple", () => {
-	it("should convert a union into an ordered tuple", () => {
-		type Actual = UnionToTuple<1 | 2 | 3 | 4 | 5 | "bob" | 6>;
-		type Expected = [1, 2, 3, 4, 5, "bob", 6];
+	it("preserves every member and the tuple length without assuming order", () => {
+		type Input = 1 | 2 | 3 | 4 | 5 | "bob" | 6;
+		type Actual = UnionToTuple<Input>;
 
-		expectTypeOf<Actual>().toEqualTypeOf<Expected>();
+		expectTypeOf<Actual[number]>().toEqualTypeOf<Input>();
+		expectTypeOf<Actual["length"]>().toEqualTypeOf<7>();
+	});
+
+	it("preserves singleton and empty unions", () => {
+		expectTypeOf<UnionToTuple<"bob">>().toEqualTypeOf<["bob"]>();
+		expectTypeOf<UnionToTuple<never>>().toEqualTypeOf<[]>();
 	});
 });

packages/types/src/index.ts

@@ -29,6 +29,7 @@ export type * from "./mapped-enum.js";
 export type * from "./mask-dates.js";
 export type * from "./mask-literals.js";
 export type * from "./maybe.js";
+export type * from "./member-of-union.js";
 export type * from "./non-empty-array.js";
 export type * from "./non-optional.js";
 export type * from "./omit-by.js";

packages/types/src/last-of-union.ts

@@ -1,11 +1,11 @@
-import type { UnionToIntersection } from "./union-to-intersection.js";
+import type { MemberOfUnion } from "./member-of-union.js";
 
 /**
- * Extracts the last type from a union.
+ * Selects a single member of a union, or `never` for `never`.
  *
- * @see {@link UnionToIntersection}
+ * @deprecated Use {@link MemberOfUnion}. Selection is unspecified and
+ * compiler-dependent; unions have no meaningful order or "last" member.
  *
  * @since 0.0.18
  */
-export type LastOfUnion<U> =
-	UnionToIntersection<U extends any ? () => U : never> extends () => infer R ? R : never;
+export type LastOfUnion<U> = MemberOfUnion<U>;

packages/types/src/member-of-union.ts

@@ -0,0 +1,13 @@
+import type { UnionToIntersection } from "./union-to-intersection.js";
+
+/**
+ * Selects a single member of a union, or `never` for `never`.
+ *
+ * Selection is unspecified and may differ between compiler versions and programs.
+ *
+ * @see {@link UnionToIntersection}
+ *
+ * @since @next
+ */
+export type MemberOfUnion<U> =
+	UnionToIntersection<U extends any ? () => U : never> extends () => infer R ? R : never;

packages/types/src/union-to-tuple.ts

@@ -1,18 +1,19 @@
-import type { LastOfUnion } from "./last-of-union.js";
+import type { MemberOfUnion } from "./member-of-union.js";
 
 /**
- * Converts a union into an ordered tuple.
+ * Converts a union into a tuple with unspecified, compiler-dependent order.
  *
- * @see {@link LastOfUnion}
+ * @see {@link MemberOfUnion}
  *
  * @example
- * type Enum = "bert" | "berta" | "bob";
+ * type Name = "bert" | "berta" | "bob";
  *
- * type EnumAsTuple = UnionToTuple<Enum>; // ["bert", "berta", "bob"]
- * type IsEnumAsTuple = IsTuple<EnumAsTuple>; // true
+ * type NameTuple = UnionToTuple<Name>;
+ * type Members = NameTuple[number]; // "bert" | "berta" | "bob"
+ * type Length = NameTuple["length"]; // 3
  *
  * @since 0.0.18
  */
 export type UnionToTuple<T> = [T] extends [never]
 	? []
-	: [...UnionToTuple<Exclude<T, LastOfUnion<T>>>, LastOfUnion<T>];
+	: [...UnionToTuple<Exclude<T, MemberOfUnion<T>>>, MemberOfUnion<T>];