Generic entities module (#108)

Author: ozsay

src/modules/entities.ts

@@ -1,10 +1,14 @@
 import { AxiosInstance } from "axios";
 import {
+  DeleteManyResult,
+  DeleteResult,
   EntitiesModule,
   EntityHandler,
+  ImportResult,
   RealtimeCallback,
   RealtimeEvent,
   RealtimeEventType,
+  SortField,
 } from "./entities.types";
 import { RoomsSocket } from "../utils/socket-utils.js";
 
@@ -54,12 +58,12 @@ export function createEntitiesModule(
  * Parses the realtime message data and extracts event information.
  * @internal
  */
-function parseRealtimeMessage(dataStr: string): RealtimeEvent | null {
+function parseRealtimeMessage<T = any>(dataStr: string): RealtimeEvent<T> | null {
   try {
     const parsed = JSON.parse(dataStr);
     return {
       type: parsed.type as RealtimeEventType,
-      data: parsed.data,
+      data: parsed.data as T,
       id: parsed.id || parsed.data?.id,
       timestamp: parsed.timestamp || new Date().toISOString(),
     };
@@ -79,17 +83,22 @@ function parseRealtimeMessage(dataStr: string): RealtimeEvent | null {
  * @returns Entity handler with CRUD methods
  * @internal
  */
-function createEntityHandler(
+function createEntityHandler<T = any>(
   axios: AxiosInstance,
   appId: string,
   entityName: string,
   getSocket: () => ReturnType<typeof RoomsSocket>
-): EntityHandler {
+): EntityHandler<T> {
   const baseURL = `/apps/${appId}/entities/${entityName}`;
 
   return {
     // List entities with optional pagination and sorting
-    async list(sort: string, limit: number, skip: number, fields: string[]) {
+    async list<K extends keyof T = keyof T>(
+      sort?: SortField<T>,
+      limit?: number,
+      skip?: number,
+      fields?: K[]
+    ): Promise<Pick<T, K>[]> {
       const params: Record<string, string | number> = {};
       if (sort) params.sort = sort;
       if (limit) params.limit = limit;
@@ -101,13 +110,13 @@ function createEntityHandler(
     },
 
     // Filter entities based on query
-    async filter(
-      query: Record<string, any>,
-      sort: string,
-      limit: number,
-      skip: number,
-      fields: string[]
-    ) {
+    async filter<K extends keyof T = keyof T>(
+      query: Partial<T>,
+      sort?: SortField<T>,
+      limit?: number,
+      skip?: number,
+      fields?: K[]
+    ): Promise<Pick<T, K>[]> {
       const params: Record<string, string | number> = {
         q: JSON.stringify(query),
       };
@@ -122,37 +131,37 @@ function createEntityHandler(
     },
 
     // Get entity by ID
-    async get(id: string) {
+    async get(id: string): Promise<T> {
       return axios.get(`${baseURL}/${id}`);
     },
 
     // Create new entity
-    async create(data: Record<string, any>) {
+    async create(data: Partial<T>): Promise<T> {
       return axios.post(baseURL, data);
     },
 
     // Update entity by ID
-    async update(id: string, data: Record<string, any>) {
+    async update(id: string, data: Partial<T>): Promise<T> {
       return axios.put(`${baseURL}/${id}`, data);
     },
 
     // Delete entity by ID
-    async delete(id: string) {
+    async delete(id: string): Promise<DeleteResult> {
       return axios.delete(`${baseURL}/${id}`);
     },
 
     // Delete multiple entities based on query
-    async deleteMany(query: Record<string, any>) {
+    async deleteMany(query: Partial<T>): Promise<DeleteManyResult> {
       return axios.delete(baseURL, { data: query });
     },
 
     // Create multiple entities in a single request
-    async bulkCreate(data: Record<string, any>[]) {
+    async bulkCreate(data: Partial<T>[]): Promise<T[]> {
       return axios.post(`${baseURL}/bulk`, data);
     },
 
     // Import entities from a file
-    async importEntities(file: File) {
+    async importEntities(file: File): Promise<ImportResult<T>> {
       const formData = new FormData();
       formData.append("file", file, file.name);
 
@@ -164,14 +173,14 @@ function createEntityHandler(
     },
 
     // Subscribe to realtime updates
-    subscribe(callback: RealtimeCallback): () => void {
+    subscribe(callback: RealtimeCallback<T>): () => void {
       const room = `entities:${appId}:${entityName}`;
 
       // Get the socket and subscribe to the room
       const socket = getSocket();
       const unsubscribe = socket.subscribeToRoom(room, {
         update_model: (msg) => {
-          const event = parseRealtimeMessage(msg.data);
+          const event = parseRealtimeMessage<T>(msg.data);
           if (!event) {
             return;
           }

src/modules/entities.types.ts

@@ -5,12 +5,14 @@ export type RealtimeEventType = "create" | "update" | "delete";
 
 /**
  * Payload received when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the data field. Defaults to `any`.
  */
-export interface RealtimeEvent {
+export interface RealtimeEvent<T = any> {
   /** The type of change that occurred */
   type: RealtimeEventType;
   /** The entity data */
-  data: any;
+  data: T;
   /** The unique identifier of the affected entity */
   id: string;
   /** ISO 8601 timestamp of when the event occurred */
@@ -19,15 +21,73 @@ export interface RealtimeEvent {
 
 /**
  * Callback function invoked when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the event data. Defaults to `any`.
+ */
+export type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;
+
+/**
+ * Result returned when deleting a single entity.
+ */
+export interface DeleteResult {
+  /** Whether the deletion was successful */
+  success: boolean;
+}
+
+/**
+ * Result returned when deleting multiple entities.
  */
-export type RealtimeCallback = (event: RealtimeEvent) => void;
+export interface DeleteManyResult {
+  /** Whether the deletion was successful */
+  success: boolean;
+  /** Number of entities that were deleted */
+  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.
  *
  * Each entity in the app gets a handler with these methods for managing data.
+ *
+ * @typeParam T - The entity type. Defaults to `any` for backward compatibility.
  */
-export interface EntityHandler {
+export interface EntityHandler<T = any> {
   /**
    * Lists records with optional pagination and sorting.
    *
@@ -36,11 +96,12 @@ export interface EntityHandler {
    *
    * **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
@@ -67,12 +128,12 @@ export interface EntityHandler {
    * 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<any>;
+    fields?: K[]
+  ): Promise<Pick<T, K>[]>;
 
   /**
    * Filters records based on a query.
@@ -82,14 +143,15 @@ export interface EntityHandler {
    *
    * **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
@@ -131,13 +193,13 @@ export interface EntityHandler {
    * );
    * ```
    */
-  filter(
-    query: Record<string, any>,
-    sort?: string,
+  filter<K extends keyof T = keyof T>(
+    query: Partial<T>,
+    sort?: SortField<T>,
     limit?: number,
     skip?: number,
-    fields?: string[]
-  ): Promise<any>;
+    fields?: K[]
+  ): Promise<Pick<T, K>[]>;
 
   /**
    * Gets a single record by ID.
@@ -154,7 +216,7 @@ export interface EntityHandler {
    * console.log(record.name);
    * ```
    */
-  get(id: string): Promise<any>;
+  get(id: string): Promise<T>;
 
   /**
    * Creates a new record.
@@ -175,7 +237,7 @@ export interface EntityHandler {
    * console.log('Created record with ID:', newRecord.id);
    * ```
    */
-  create(data: Record<string, any>): Promise<any>;
+  create(data: Partial<T>): Promise<T>;
 
   /**
    * Updates an existing record.
@@ -205,7 +267,7 @@ export interface EntityHandler {
    * });
    * ```
    */
-  update(id: string, data: Record<string, any>): Promise<any>;
+  update(id: string, data: Partial<T>): Promise<T>;
 
   /**
    * Deletes a single record by ID.
@@ -219,10 +281,10 @@ export interface EntityHandler {
    * ```typescript
    * // Delete a record
    * const result = await base44.entities.MyEntity.delete('entity-123');
-   * console.log('Deleted:', result);
+   * console.log('Deleted:', result.success);
    * ```
    */
-  delete(id: string): Promise<any>;
+  delete(id: string): Promise<DeleteResult>;
 
   /**
    * Deletes multiple records matching a query.
@@ -244,7 +306,7 @@ export interface EntityHandler {
    * console.log('Deleted:', result);
    * ```
    */
-  deleteMany(query: Record<string, any>): Promise<any>;
+  deleteMany(query: Partial<T>): Promise<DeleteManyResult>;
 
   /**
    * Creates multiple records in a single request.
@@ -265,7 +327,7 @@ export interface EntityHandler {
    * ]);
    * ```
    */
-  bulkCreate(data: Record<string, any>[]): Promise<any>;
+  bulkCreate(data: Partial<T>[]): Promise<T[]>;
 
   /**
    * Imports records from a file.
@@ -274,7 +336,7 @@ export interface EntityHandler {
    * 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
@@ -283,12 +345,14 @@ export interface EntityHandler {
    *   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.
@@ -315,7 +379,7 @@ export interface EntityHandler {
    * unsubscribe();
    * ```
    */
-  subscribe(callback: RealtimeCallback): () => void;
+  subscribe(callback: RealtimeCallback<T>): () => void;
 }
 
 /**
@@ -364,5 +428,5 @@ export interface EntitiesModule {
    * base44.entities.AnotherEntity
    * ```
    */
-  [entityName: string]: EntityHandler;
+  [entityName: string]: EntityHandler<any>;
 }