Aggregates definitions and their respective queries must be in the same file

[tomredman]

When I have my TableAggregate's defined in their own and attempt to use them in another file, I get an insurmountable typescript error: Type instantiation is excessively deep and possibly infinite.

This query results in the following error:

// convex/campaigns/queries.ts
export const getSentCountForCampaign = query({
  args: {
    campaignId: v.id("campaigns"),
  },
  handler: async (ctx, args) => {
    return await aggregateEmailEventsSent.count(ctx, {
      namespace: args.campaignId,
      bounds: {},
    });
  },
});

// Compilation error:
> ✖ TypeScript typecheck via `tsc` failed.
> convex | To ignore failing typecheck, use `--typecheck=disable`.
> convex/campaigns/queries.ts:77:15 - error TS2589: Type instantiation is excessively deep and possibly infinite.
> convex |
> convex | 77       bounds: {},
> convex |                  ~~
> convex |
> convex | Found 1 error in convex/campaigns/queries.ts:77

I can't get this two-file structure to compile without the type instantiation error:

// convex/aggregates/campaigns.ts
import { v } from "convex/values";
import { components } from "../_generated/api";
import { DataModel, Id } from "../_generated/dataModel";
import { query } from "../_generated/server";
import { TableAggregate } from "@convex-dev/aggregate";

/*
 * Aggregates
 */
export const aggregateEmailEventsSent = new TableAggregate<{
  Namespace: Id<"campaigns">;
  Key: number;
  DataModel: DataModel;
  TableName: "emails";
}>(components.aggregateEmailEventsSent, {
  namespace: (doc) => doc.campaignId,
  sortKey: (doc) => doc._creationTime,
  sumValue: () => 1,
});

// convex/campaigns/queries.ts

export const getSentCountForCampaign = query({
  args: {
    campaignId: v.id("campaigns"),
  },
  handler: async (ctx, args) => {
    const forCampaign = {
      namespace: args.campaignId,
      bounds: {},
    };
    return await aggregateEmailEventsSent.count(ctx, forCampaign);
  },
});

However, if both of these are in the same file, it works:

// convex/aggregates/campaigns.ts
import { v } from "convex/values";
import { components } from "../_generated/api";
import { DataModel, Id } from "../_generated/dataModel";
import { query } from "../_generated/server";
import { TableAggregate } from "@convex-dev/aggregate";

/*
 * Aggregates
 */
export const aggregateEmailEventsSent = new TableAggregate<{
  Namespace: Id<"campaigns">;
  Key: number;
  DataModel: DataModel;
  TableName: "emails";
}>(components.aggregateEmailEventsSent, {
  namespace: (doc) => doc.campaignId,
  sortKey: (doc) => doc._creationTime,
  sumValue: () => 1,
});

export const getSentCountForCampaign = query({
  args: {
    campaignId: v.id("campaigns"),
  },
  handler: async (ctx, args) => {
    const forCampaign = {
      namespace: args.campaignId,
      bounds: {},
    };
    return await aggregateEmailEventsSent.count(ctx, forCampaign);
  },
});

Notably, this has been a little fickle. I got it to work in in the first way (two files) after deleting and regenerating the Convex code, in addition to changing this line (the error occurs no matter what when I try to inline the Bounds object):

This works in both cases:

const forCampaign = {
  namespace: args.campaignId,
  bounds: {},
};
return await aggregateEmailEventsSent.count(ctx, forCampaign);

This works only if defined in the same file as the aggregate:

return await aggregateEmailEventsSent.count(ctx, {
  namespace: args.campaignId,
  bounds: {},
});

[ianmacartney]

So the campaigns doesn't import from the queries otherwise? It sounds like a circular reference somewhere. To prove that out, does having the aggregate in its own file with nothing else fix it?

[deepso7]

for me the issue is bit different, everything is in the same file only

This doesn't throw this error: Type instantiation is excessively deep and possibly infinite.

export const streamViewsAggregate = new TableAggregate<{
  Key: string; // videoId
  DataModel: DataModel;
  TableName: "streamViewEvents";
}>(components.streamViewsAggregate, {
  sortKey: (doc) => doc.streamId,
});

export const getViews = query({
  args: {
    streamId: v.id("streams"),
  },
  handler: async (ctx, args) => {
    return await streamViewsAggregate.count(ctx, {
      bounds: {
        lower: { key: args.streamId, inclusive: true },
        upper: { key: args.streamId, inclusive: true },
      },
    });
  },
});

but this code does, I think both do the same thing

export const getViews = query({
  args: {
    streamId: v.id("streams"),
  },
  handler: async (ctx, args) => {
    return await streamViewsAggregate.count(ctx, {
      bounds: {
        prefix: [args.streamId],  // here it shows the error
      },
    });
  },
});

[ianmacartney]

There's some docs on solving circular dependencies, but the gist is that you need to add explicit types to the handler function / variables when typescript gets into these circular situations. e.g. handler: async (ctx, args): Promise<yourtype> => {

…

On Thu, Oct 2, 2025 at 1:36 PM Deepso ***@***.***> wrote: *deepso7* left a comment (get-convex/aggregate#25) <#25 (comment)> for me the issue is bit different, everything is in the same file only This doesn't throw this error: Type instantiation is excessively deep and possibly infinite. export const streamViewsAggregate = new TableAggregate<{ Key: string; // videoId DataModel: DataModel; TableName: "streamViewEvents"; }>(components.streamViewsAggregate, { sortKey: (doc) => doc.streamId, }); export const getViews = query({ args: { streamId: v.id("streams"), }, handler: async (ctx, args) => { return await streamViewsAggregate.count(ctx, { bounds: { lower: { key: args.streamId, inclusive: true }, upper: { key: args.streamId, inclusive: true }, }, }); }, }); but this code does, I think both do the same thing export const getViews = query({ args: { streamId: v.id("streams"), }, handler: async (ctx, args) => { return await streamViewsAggregate.count(ctx, { bounds: { prefix: [args.streamId], // here it shows the error }, }); }, }); — Reply to this email directly, view it on GitHub <#25 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW3YPEKZHHMVDTKVSX33VWEDBAVCNFSM6AAAAACIETDOK2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGNRSHA2TIMJXGU> . You are receiving this because you commented.Message ID: ***@***.***>

[deepso7]

I tries this
but still the same issue

export const getChannelViews = query({
  args: {
    channelId: v.id("channels"),
  },
  handler: async (ctx, args): Promise<number> => {
    const count: number = await channelViewsAggregate.count(ctx, {
      bounds: {
        prefix: [args.channelId], // red squigly lines on args.channelId
      },
    });

    return count;
  },
});

[ianmacartney]

can you make a repo with a minimal reproduction for me? that would make it a lot easier to diagnose if there's a deeper type issue or if it's something specific to your setup

…

On Fri, Oct 3, 2025 at 2:48 AM Deepso ***@***.***> wrote: *deepso7* left a comment (get-convex/aggregate#25) <#25 (comment)> I tries this but still the same issue export const getChannelViews = query({ args: { channelId: v.id("channels"), }, handler: async (ctx, args): Promise<number> => { const count: number = await channelViewsAggregate.count(ctx, { bounds: { prefix: [args.channelId], // red squigly lines on args.channelId }, }); return count; },}); — Reply to this email directly, view it on GitHub <#25 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW3HZ5REQF7LVUC6HVL3VZA6BAVCNFSM6AAAAACIETDOK2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGNRVGA2DINJRGA> . You are receiving this because you commented.Message ID: ***@***.***>

[Niall-Kenny]

I'm also getting this error.

@ianmacartney You can reproduce this by:

1. npm create convex@latest
2. Once run, run npm install @convex-dev/aggregate in the project
3. add convex.config.ts (inside convex folder):

// convex/convex.config.ts
import aggregate from "@convex-dev/aggregate/convex.config";
import { defineApp } from "convex/server";

const app = defineApp();
app.use(aggregate, { name: "numbers" });
export default app;

4. add aggregates.ts (inside convex folder):

import { TableAggregate } from "@convex-dev/aggregate";
import { v } from "convex/values";
import { components } from "./_generated/api";
import { DataModel, Id } from "./_generated/dataModel";
import { query } from "./_generated/server";

export const aggregateByTotalBookingCount = new TableAggregate<{
  Key: Id<"numbers">;
  DataModel: DataModel;
  TableName: "numbers";
}>(components.numbers, {
  sortKey: (doc) => doc._id,
});

export const MyFunc = query({
  args: {
    id: v.id("numbers"),
  },
  handler: async (ctx, { id }) => {
    await aggregateByTotalBookingCount.sum(ctx, {
      bounds: { prefix: id },
    });
  },
});