feat(entities): new entity APIs — cursor pages, count, distinct, aggregate, upsert

Wraps the scan-free entity routes added in base44-dev/apper#24939. Fifty apps with
the deepest `skip` reads were reviewed; none paged because a user asked for page N.
Every loop existed to get a number, to check whether a key already exists, to walk a
table with a resume point that is not an offset, or to list a field's distinct values.

- list(options) / filter(query, options): pass an options object {sort, limit,
  cursor, fields} instead of positional args to read one cursor page; returns
  {items, next_cursor, has_more}. Positional calls are unchanged. skip is
  documented as deprecated for loops.
- count(query?): number of readable records matching a filter.
- distinct(field, query?): {values, truncated}, capped at 5000 values.
- aggregate(spec): group_by / date_bucket / count / sum / avg / min / max /
  count_distinct / having / sort / limit; returns {rows, truncated}.
- upsert(records, {key}): create or update by a natural key, up to 500 records.

New public types are exported and listed in types-to-expose.json.

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

Author: arosenan

scripts/mintlify-post-processing/types-to-expose.json

@@ -19,9 +19,17 @@
   "DeleteManyResult",
   "DeleteResult",
   "EntitiesModule",
+  "EntityAggregateResult",
+  "EntityAggregateSpec",
+  "EntityDateBucketUnit",
+  "EntityDistinctResult",
   "EntityHandler",
+  "EntityListOptions",
+  "EntityPage",
   "EntityRecord",
   "EntityTypeRegistry",
+  "EntityUpsertOptions",
+  "EntityUpsertResult",
   "FunctionName",
   "FunctionNameRegistry",
   "FunctionsModule",

src/index.ts

@@ -39,12 +39,20 @@ export type {
   DeleteManyResult,
   DeleteResult,
   EntitiesModule,
+  EntityAggregateResult,
+  EntityAggregateSpec,
+  EntityDateBucketUnit,
+  EntityDistinctResult,
   EntityFilterOperators,
   EntityFilterQuery,
   EntityFilterValue,
   EntityHandler,
+  EntityListOptions,
+  EntityPage,
   EntityRecord,
   EntityTypeRegistry,
+  EntityUpsertOptions,
+  EntityUpsertResult,
   ImportResult,
   RealtimeEventType,
   RealtimeEvent,

src/modules/entities.ts

@@ -3,8 +3,15 @@ import {
   DeleteManyResult,
   DeleteResult,
   EntitiesModule,
+  EntityAggregateResult,
+  EntityAggregateSpec,
+  EntityDistinctResult,
   EntityFilterQuery,
   EntityHandler,
+  EntityListOptions,
+  EntityPage,
+  EntityUpsertOptions,
+  EntityUpsertResult,
   ImportResult,
   RealtimeCallback,
   RealtimeEvent,
@@ -75,6 +82,20 @@ function parseRealtimeMessage<T = any>(dataStr: string): RealtimeEvent<T> | null
   }
 }
 
+function isListOptions(value: unknown): value is EntityListOptions<any, any> {
+  return typeof value === "object" && value !== null;
+}
+
+function pageParams(options: EntityListOptions<any, any>): Record<string, string | number> {
+  const params: Record<string, string | number> = {};
+  if (options.sort) params.sort = options.sort;
+  if (options.limit) params.limit = options.limit;
+  if (options.cursor) params.cursor = options.cursor;
+  if (options.fields)
+    params.fields = Array.isArray(options.fields) ? options.fields.join(",") : options.fields;
+  return params;
+}
+
 /**
  * Creates a handler for a specific entity.
  *
@@ -94,15 +115,18 @@ function createEntityHandler<T = any>(
   const baseURL = `/apps/${appId}/entities/${entityName}`;
 
   return {
-    // List entities with optional pagination and sorting
+    // List entities. Positional args read one array; an options object reads one cursor page.
     async list<K extends keyof T = keyof T>(
-      sort?: SortField<T>,
+      sortOrOptions?: SortField<T> | EntityListOptions<T, K>,
       limit?: number,
       skip?: number,
       fields?: K[]
-    ): Promise<Pick<T, K>[]> {
+    ): Promise<any> {
+      if (isListOptions(sortOrOptions)) {
+        return axios.get(`${baseURL}/page`, { params: pageParams(sortOrOptions) });
+      }
       const params: Record<string, string | number> = {};
-      if (sort) params.sort = sort;
+      if (sortOrOptions) params.sort = sortOrOptions;
       if (limit) params.limit = limit;
       if (skip) params.skip = skip;
       if (fields)
@@ -111,19 +135,21 @@ function createEntityHandler<T = any>(
       return axios.get(baseURL, { params });
     },
 
-    // Filter entities based on query
+    // Filter entities. Positional args read one array; an options object reads one cursor page.
     async filter<K extends keyof T = keyof T>(
       query: EntityFilterQuery<T>,
-      sort?: SortField<T>,
+      sortOrOptions?: SortField<T> | EntityListOptions<T, K>,
       limit?: number,
       skip?: number,
       fields?: K[]
-    ): Promise<Pick<T, K>[]> {
-      const params: Record<string, string | number> = {
-        q: JSON.stringify(query),
-      };
+    ): Promise<any> {
+      const q = JSON.stringify(query);
+      if (isListOptions(sortOrOptions)) {
+        return axios.get(`${baseURL}/page`, { params: { q, ...pageParams(sortOrOptions) } });
+      }
+      const params: Record<string, string | number> = { q };
 
-      if (sort) params.sort = sort;
+      if (sortOrOptions) params.sort = sortOrOptions;
       if (limit) params.limit = limit;
       if (skip) params.skip = skip;
       if (fields)
@@ -167,6 +193,37 @@ function createEntityHandler<T = any>(
       return axios.patch(`${baseURL}/update-many`, { query, data });
     },
 
+    // Count entities matching a query
+    async count(query?: EntityFilterQuery<T>): Promise<number> {
+      const params: Record<string, string> = {};
+      if (query) params.q = JSON.stringify(query);
+      const result: { count: number } = await axios.get(`${baseURL}/count`, { params });
+      return result.count;
+    },
+
+    // Distinct values of one field
+    async distinct<K extends keyof T & string>(
+      field: K,
+      query?: EntityFilterQuery<T>
+    ): Promise<EntityDistinctResult<T[K]>> {
+      const params: Record<string, string> = { field };
+      if (query) params.q = JSON.stringify(query);
+      return axios.get(`${baseURL}/distinct`, { params });
+    },
+
+    // Server-side group-by aggregation
+    async aggregate(spec: EntityAggregateSpec<T>): Promise<EntityAggregateResult> {
+      return axios.post(`${baseURL}/aggregate`, spec);
+    },
+
+    // Create or update by a natural key
+    async upsert(
+      records: Partial<T>[],
+      options: EntityUpsertOptions<T>
+    ): Promise<EntityUpsertResult<T>> {
+      return axios.post(`${baseURL}/upsert`, { records, key: options.key });
+    },
+
     // Update multiple entities by ID, each with its own update data
     async bulkUpdate(data: (Partial<T> & { id: string })[]): Promise<T[]> {
       return axios.put(`${baseURL}/bulk`, data);