Enhance entity handling with typed sorting and import results

- Introduced `SortField` type for improved sorting parameter handling in list and filter methods.
- Updated `importEntities` method to return a structured `ImportResult` type, providing detailed import status and output.
- Modified list and filter methods to support generic field selection, enhancing type safety and flexibility.

Author: ozsay

src/modules/entities.ts

@@ -4,9 +4,11 @@ import {
   DeleteResult,
   EntitiesModule,
   EntityHandler,
+  ImportResult,
   RealtimeCallback,
   RealtimeEvent,
   RealtimeEventType,
+  SortField,
 } from "./entities.types";
 import { RoomsSocket } from "../utils/socket-utils.js";
 
@@ -91,12 +93,12 @@ function createEntityHandler<T = any>(
 
   return {
     // List entities with optional pagination and sorting
-    async list(
-      sort?: string,
+    async list<K extends keyof T = keyof T>(
+      sort?: SortField<T>,
       limit?: number,
       skip?: number,
-      fields?: string[]
-    ): Promise<T[]> {
+      fields?: K[]
+    ): Promise<Pick<T, K>[]> {
       const params: Record<string, string | number> = {};
       if (sort) params.sort = sort;
       if (limit) params.limit = limit;
@@ -108,13 +110,13 @@ function createEntityHandler<T = any>(
     },
 
     // Filter entities based on query
-    async filter(
+    async filter<K extends keyof T = keyof T>(
       query: Partial<T>,
-      sort?: string,
+      sort?: SortField<T>,
       limit?: number,
       skip?: number,
-      fields?: string[]
-    ): Promise<T[]> {
+      fields?: K[]
+    ): Promise<Pick<T, K>[]> {
       const params: Record<string, string | number> = {
         q: JSON.stringify(query),
       };
@@ -159,7 +161,7 @@ function createEntityHandler<T = any>(
     },
 
     // Import entities from a file
-    async importEntities(file: File): Promise<any> {
+    async importEntities(file: File): Promise<ImportResult<T>> {
       const formData = new FormData();
       formData.append("file", file, file.name);
 

src/modules/entities.types.ts

@@ -44,6 +44,42 @@ export interface DeleteManyResult {
   deleted: number;
 }
 
+/**
+ * Result returned when importing entities from a file.
+ *
+ * @typeParam T - The entity type for imported records. Defaults to `any`.
+ */
+export interface ImportResult<T = any> {
+  /** Status of the import operation */
+  status: "success" | "error";
+  /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement" */
+  details: string | null;
+  /** Array of created entity objects when successful, or null on error */
+  output: T[] | null;
+}
+
+/**
+ * Sort field type for entity queries.
+ *
+ * Supports ascending (no prefix or `'+'`) and descending (`'-'`) sorting.
+ *
+ * @typeParam T - The entity type to derive sortable fields from.
+ *
+ * @example
+ * ```typescript
+ * // Ascending sort (default)
+ * 'created_date'
+ * '+created_date'
+ *
+ * // Descending sort
+ * '-created_date'
+ * ```
+ */
+export type SortField<T> =
+  | (keyof T & string)
+  | `+${keyof T & string}`
+  | `-${keyof T & string}`;
+
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
@@ -60,11 +96,12 @@ export interface EntityHandler<T = any> {
    *
    * **Note:** The maximum limit is 5,000 items per request.
    *
+   * @typeParam K - The fields to include in the response. Defaults to all fields.
    * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
    * @param limit - Maximum number of results to return. Defaults to `50`.
    * @param skip - Number of results to skip for pagination. Defaults to `0`.
    * @param fields - Array of field names to include in the response. Defaults to all fields.
-   * @returns Promise resolving to an array of records.
+   * @returns Promise resolving to an array of records with selected fields.
    *
    * @example
    * ```typescript
@@ -91,12 +128,12 @@ export interface EntityHandler<T = any> {
    * const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
    * ```
    */
-  list(
-    sort?: string,
+  list<K extends keyof T = keyof T>(
+    sort?: SortField<T>,
     limit?: number,
     skip?: number,
-    fields?: string[]
-  ): Promise<T[]>;
+    fields?: K[]
+  ): Promise<Pick<T, K>[]>;
 
   /**
    * Filters records based on a query.
@@ -106,14 +143,15 @@ export interface EntityHandler<T = any> {
    *
    * **Note:** The maximum limit is 5,000 items per request.
    *
+   * @typeParam K - The fields to include in the response. Defaults to all fields.
    * @param query - Query object with field-value pairs. Each key should be a field name
    * from your entity schema, and each value is the criteria to match. Records matching all
    * specified criteria are returned. Field names are case-sensitive.
    * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
    * @param limit - Maximum number of results to return. Defaults to `50`.
    * @param skip - Number of results to skip for pagination. Defaults to `0`.
    * @param fields - Array of field names to include in the response. Defaults to all fields.
-   * @returns Promise resolving to an array of filtered records.
+   * @returns Promise resolving to an array of filtered records with selected fields.
    *
    * @example
    * ```typescript
@@ -155,13 +193,13 @@ export interface EntityHandler<T = any> {
    * );
    * ```
    */
-  filter(
+  filter<K extends keyof T = keyof T>(
     query: Partial<T>,
-    sort?: string,
+    sort?: SortField<T>,
     limit?: number,
     skip?: number,
-    fields?: string[]
-  ): Promise<T[]>;
+    fields?: K[]
+  ): Promise<Pick<T, K>[]>;
 
   /**
    * Gets a single record by ID.
@@ -298,7 +336,7 @@ export interface EntityHandler<T = any> {
    * The file format should match your entity structure. Requires a browser environment and can't be used in the backend.
    *
    * @param file - File object to import.
-   * @returns Promise resolving to the import result.
+   * @returns Promise resolving to the import result containing status, details, and created records.
    *
    * @example
    * ```typescript
@@ -307,12 +345,14 @@ export interface EntityHandler<T = any> {
    *   const file = event.target.files?.[0];
    *   if (file) {
    *     const result = await base44.entities.MyEntity.importEntities(file);
-   *     console.log(`Imported ${result.count} records`);
+   *     if (result.status === 'success' && result.output) {
+   *       console.log(`Imported ${result.output.length} records`);
+   *     }
    *   }
    * };
    * ```
    */
-  importEntities(file: File): Promise<any>;
+  importEntities(file: File): Promise<ImportResult<T>>;
 
   /**
    * Subscribes to realtime updates for all records of this entity type.