Bug Report: TypeScript Error "Type instantiation is excessively deep and possibly infinite" with Complex Supabase Joins

[ElectricCodeGuy]

Bug report

• [x] I confirm this is a bug with Supabase, not with my own application.
• [x] I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

When using Supabase's client to perform a query that joins multiple tables with many columns (around 14-15 tables with 40-50 columns total), TypeScript throws the error: "Type instantiation is excessively deep and possibly infinite". The query itself works perfectly, but TypeScript cannot handle the type inference for such complex joins.

To Reproduce

Steps to reproduce the behavior:

1. Create a schema with 15+ related tables
2. Set up a main lookup table that references these tables
3. Create a query that joins the main table with these 15+ tables
4. Try to use TypeScript's type inference with the query result

Code example:

export const fetchItemBySlug = async (slug: string) => {
  const supabase = createClient();
  
  // This query joins 15+ tables, causing TypeScript to not work
  const { data, error } = await supabase
    .from('main_items')
    .select(`
      id,
      search_id,
      database_type,
      table1 (
        item_id,
        title,
        date_published,
        categories
      ),
      table2 (
        item_id,
        title,
        content,
        tags
      ),
      // ... more tables with similar structure
      table15 (
        item_id,
        title,
        description,
        date
      )
    `)
    .eq('search_key', slug)
    .single();

  // TypeScript error occurs at this point
  return data;
};

Expected behavior

TypeScript should be able to infer or handle the return type from Supabase's query builder even with complex joins, or gracefully degrade to a simplified type without throwing errors.

Screenshots

N/A

System information

• OS: Windows with WSL2 Ubunto
• Browser: Chrome
• Version of supabase-js: .249.1
• Version of Node.js: 22
• TypeScript version: 5.8 (also happens on 5.7)
• Next.js version: 15.2 (using App Router)

Additional context

I've implemented a lookup/central table that references many other tables to efficiently fetch data from multiple sources in a single query. This works perfectly from a database perspective and is very performant.

Currently, I'm working around this issue by:

1. Using // @ts-ignore to suppress the TypeScript error
2. Using type assertions like as unknown as { data: any; error: any }

However, both solutions sacrifice type safety.

The issue seems to be related to TypeScript's recursion limits when dealing with deeply nested types generated from complex joins. Is there a recommended approach for handling complex join queries with the Supabase client without running into TypeScript limitations?

Perhaps a solution could be to implement a "simplified type mode" for very complex queries, where TypeScript could generate a less detailed but still functional type that doesn't exceed its recursion limits?

I also found a reddit post discussing this issue: https://www.reddit.com/r/typescript/comments/1c3r9gx/what_are_some_good_strategies_to_avoid_type/

Typescript also becomes painfully slow when the error occurs (only when working inside the file)