fix: prevent subtype reduction from collapsing collection and paginator return types

When a controller returns either a collection or paginator from the
serialize method, TypeScript's subtype reduction collapses the union
because the paginator type (with metadata) is structurally assignable
to the collection type (without metadata).

Add `metadata?: never` to the wrapped collection serialize overload
to make the two types structurally incompatible, preserving the union.

Author: thetutlage

src/base_serializer.ts

@@ -189,7 +189,11 @@ export abstract class BaseSerializer<
   serialize<ResourceCollection extends CollectionContract<any, any, any>>(
     collection: ResourceCollection,
     resolver?: ContainerResolver<any>
-  ): Promise<UnpackAsTopLevelCollection<ResourceCollection, Wrappers['Wrap']>>
+  ): Promise<
+    Wrappers['Wrap'] extends string
+      ? UnpackAsTopLevelCollection<ResourceCollection, Wrappers['Wrap']> & { metadata?: never }
+      : UnpackAsTopLevelCollection<ResourceCollection, Wrappers['Wrap']>
+  >
 
   /**
    * Serializes a Paginator resource into paginated data with metadata.

tests/transformer.spec.ts

@@ -1574,10 +1574,10 @@ test.group('Transformer | wrapping', () => {
     )
     type UserData = InferData<UserTransformer>
 
-    expectTypeOf(userData).toEqualTypeOf<{ data: UserData[] }>()
-    expectTypeOf(userData).toEqualTypeOf<{
-      data: { id: number; fullName: string | null; email: string }[]
-    }>()
+    expectTypeOf(userData).toEqualTypeOf<{ data: UserData[] } & { metadata?: never }>()
+    expectTypeOf(userData).toEqualTypeOf<
+      { data: { id: number; fullName: string | null; email: string }[] } & { metadata?: never }
+    >()
 
     assert.deepEqual(userData, { data: [{ id: 1, fullName: null, email: 'foo@bar.com' }] })
   })
@@ -1627,6 +1627,51 @@ test.group('Transformer | wrapping', () => {
     })
   })
 
+  test('return type is a union when controller returns collection or paginator', async ({
+    expectTypeOf,
+  }) => {
+    class User {
+      declare id: number
+      declare fullName: string | null
+      declare email: string
+    }
+    class UserTransformer extends BaseTransformer<User> {
+      toObject() {
+        return {
+          id: this.resource.id,
+          fullName: this.resource.fullName,
+          email: this.resource.email,
+        }
+      }
+    }
+
+    type UserData = InferData<UserTransformer>
+
+    async function handler(cond: boolean) {
+      if (cond) {
+        return wrappedApiSerializer.serialize(
+          UserTransformer.paginate([new User()], {}),
+          container.createResolver()
+        )
+      }
+      return wrappedApiSerializer.serialize(
+        UserTransformer.transform([new User()]),
+        container.createResolver()
+      )
+    }
+
+    type Result = Awaited<ReturnType<typeof handler>>
+
+    expectTypeOf<Result>().not.toEqualTypeOf<{ data: UserData[] } & { metadata?: never }>()
+    expectTypeOf<Result>().toEqualTypeOf<
+      | ({ data: UserData[] } & { metadata?: never })
+      | {
+          data: UserData[]
+          metadata: { currentPage: number; totalItems: number }
+        }
+    >()
+  })
+
   test('only wrap top-level resources', async ({ assert, expectTypeOf }) => {
     class User {
       declare id: number