entities: align the API with common practice

- aggregate spec: `query` (not `match`), camelCase keys (`groupBy`, `dateBucket`,
  `countDistinct`), and no rule against combining countDistinct with other measures
- cursor pages default to 100 rows; the maximum stays 5,000

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: arosenan

src/modules/entities.ts

@@ -81,6 +81,8 @@ function parseRealtimeMessage<T = any>(dataStr: string): RealtimeEvent<T> | null
   }
 }
 
+const DEFAULT_PAGE_LIMIT = 100;
+
 function isListOptions(value: unknown): value is EntityListOptions<any, any> {
   return typeof value === "object" && value !== null;
 }
@@ -128,7 +130,7 @@ function createEntityHandler<T = any>(
     const params: Record<string, string | number> = {};
     if (query) params.q = JSON.stringify(query);
     if (options.sort) params.sort = options.sort;
-    if (options.limit) params.limit = options.limit;
+    params.limit = options.limit || DEFAULT_PAGE_LIMIT;
     if (options.cursor) params.cursor = options.cursor;
     if (options.fields) params.fields = fieldsParam(options.fields)!;
     return axios.get(`${baseURL}/v2/list`, { params });

src/modules/entities.types.ts

@@ -66,7 +66,7 @@ export interface UpdateManyResult {
 export interface EntityListOptions<T, K extends keyof T = keyof T> {
   /** Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`. Every page of one walk must use the same sort. */
   sort?: SortField<T>;
-  /** Maximum number of records per page, up to 5,000. Defaults to 5,000. */
+  /** Maximum number of records per page, up to 5,000. Defaults to 100. */
   limit?: number;
   /** `next_cursor` from the previous page. Omit or pass `null` for the first page. */
   cursor?: string | null;
@@ -90,7 +90,7 @@ export interface EntityPage<T> {
 }
 
 /**
- * Time unit for {@linkcode EntityAggregateSpec.date_bucket | date_bucket}.
+ * Time unit for {@linkcode EntityAggregateSpec.dateBucket | dateBucket}.
  */
 export type EntityDateBucketUnit = "day" | "week" | "month" | "year";
 
@@ -104,11 +104,11 @@ export type EntityDateBucketUnit = "day" | "week" | "month" | "year";
  */
 export interface EntityAggregateSpec<T> {
   /** Filter applied before grouping, in the same form {@linkcode EntityHandler.filter | filter()} accepts. Defaults to all records. */
-  match?: EntityFilterQuery<T>;
+  query?: EntityFilterQuery<T>;
   /** Field, or up to four fields, to group by. Omit to get one total row. */
-  group_by?: (keyof T & string) | (keyof T & string)[];
+  groupBy?: (keyof T & string) | (keyof T & string)[];
   /** Group by a time bucket of a date field. `created_date` and `updated_date` support every unit; date fields of your schema support `day`, `month` and `year`. */
-  date_bucket?: { field: keyof T & string; unit: EntityDateBucketUnit };
+  dateBucket?: { field: keyof T & string; unit: EntityDateBucketUnit };
   /** Whether to include the number of records per group as `count`. Defaults to `true`. */
   count?: boolean;
   /** Field, or fields, to sum. Each appears in the rows as `sum_<field>`. */
@@ -119,8 +119,8 @@ export interface EntityAggregateSpec<T> {
   min?: (keyof T & string) | (keyof T & string)[];
   /** Field, or fields, to take the maximum of. Each appears in the rows as `max_<field>`. */
   max?: (keyof T & string) | (keyof T & string)[];
-  /** Field whose distinct values to count per group, returned as `count_distinct_<field>`. Can't be combined with `count`, `sum`, `avg`, `min` or `max`. */
-  count_distinct?: keyof T & string;
+  /** Field whose distinct values to count per group, returned as `count_distinct_<field>`. */
+  countDistinct?: keyof T & string;
   /** Filter on the computed fields, applied after grouping. For example `{ count: { $gt: 1 } }` keeps only duplicated groups. */
   having?: Record<string, any>;
   /** Computed or group field to sort the rows by, with a `-` prefix for descending. For example `'-count'`. */
@@ -792,8 +792,8 @@ export interface EntityHandler<T = any> {
    * ```typescript
    * // Sales per agent this month, biggest first
    * const { rows } = await base44.entities.Sale.aggregate({
-   *   match: { sale_date: { $gte: '2026-09-01' } },
-   *   group_by: 'agent_id',
+   *   query: { sale_date: { $gte: '2026-09-01' } },
+   *   groupBy: 'agent_id',
    *   sum: 'amount',
    *   sort: '-sum_amount'
    * });
@@ -804,15 +804,15 @@ export interface EntityHandler<T = any> {
    * ```typescript
    * // Records created per day
    * const { rows } = await base44.entities.Visit.aggregate({
-   *   date_bucket: { field: 'created_date', unit: 'day' }
+   *   dateBucket: { field: 'created_date', unit: 'day' }
    * });
    * ```
    *
    * @example
    * ```typescript
    * // Find duplicated external ids
    * const { rows } = await base44.entities.Contact.aggregate({
-   *   group_by: 'external_id',
+   *   groupBy: 'external_id',
    *   having: { count: { $gt: 1 } }
    * });
    * ```
@@ -821,8 +821,8 @@ export interface EntityHandler<T = any> {
    * ```typescript
    * // Unique visitors per page
    * const { rows } = await base44.entities.PageView.aggregate({
-   *   group_by: 'path',
-   *   count_distinct: 'session_id'
+   *   groupBy: 'path',
+   *   countDistinct: 'session_id'
    * });
    * ```
    */

tests/types/entities-primitives.types.ts

@@ -14,29 +14,29 @@ interface Sale {
 }
 
 const perAgent = {
-  match: { sale_date: { $gte: "2026-09-01" } },
-  group_by: "agent_id",
+  query: { sale_date: { $gte: "2026-09-01" } },
+  groupBy: "agent_id",
   sum: ["amount"],
   avg: "amount",
   sort: "-sum_amount",
   limit: 50,
 } satisfies EntityAggregateSpec<Sale>;
 
 const perDay = {
-  date_bucket: { field: "created_date", unit: "day" },
-  count_distinct: "agent_id",
+  dateBucket: { field: "created_date", unit: "day" },
+  countDistinct: "agent_id",
 } satisfies EntityAggregateSpec<Sale>;
 
 const duplicates = {
-  group_by: ["agent_id", "store"],
+  groupBy: ["agent_id", "store"],
   having: { count: { $gt: 1 } },
 } satisfies EntityAggregateSpec<Sale>;
 
 // @ts-expect-error unknown field names are rejected
-const badGroup = { group_by: "region" } satisfies EntityAggregateSpec<Sale>;
+const badGroup = { groupBy: "region" } satisfies EntityAggregateSpec<Sale>;
 
 // @ts-expect-error unknown bucket unit
-const badUnit = { date_bucket: { field: "created_date", unit: "hour" } } satisfies EntityAggregateSpec<Sale>;
+const badUnit = { dateBucket: { field: "created_date", unit: "hour" } } satisfies EntityAggregateSpec<Sale>;
 
 const firstPage = {
   sort: "-created_date",

tests/unit/entities-primitives.test.ts

@@ -70,10 +70,10 @@ describe("Entities scan-free primitives", () => {
     expect(scope.isDone()).toBe(true);
   });
 
-  test("list() with an options object reads the first page when cursor is null", async () => {
+  test("list() with an options object reads the first page when cursor is null, 100 rows by default", async () => {
     scope
       .get(`${base}/v2/list`)
-      .query((q) => q.sort === "amount" && q.cursor === undefined && q.q === undefined)
+      .query((q) => q.sort === "amount" && q.limit === "100" && q.cursor === undefined && q.q === undefined)
       .reply(200, { items: [], next_cursor: null, has_more: false });
 
     const page = await base44.entities.Order.list({ sort: "amount", cursor: null });
@@ -118,8 +118,8 @@ describe("Entities scan-free primitives", () => {
 
   test("aggregate() posts the spec as-is to /aggregate", async () => {
     const spec = {
-      match: { status: "paid" },
-      group_by: "agent_id",
+      query: { status: "paid" },
+      groupBy: "agent_id",
       sum: "amount",
       having: { count: { $gt: 1 } },
       sort: "-sum_amount",