align comments

Author: kfirstri

src/modules/agents.types.ts

@@ -4,7 +4,7 @@ import { ModelFilterParams } from "../types.js";
 
 /**
  * Registry of agent names.
- * Augmented by `base44 types generate` to enable autocomplete for agent names.
+ * Augment this interface to enable autocomplete for agent names.
  */
 export interface AgentNameRegistry {}
 

src/modules/entities.types.ts

@@ -5,7 +5,9 @@ export type RealtimeEventType = "create" | "update" | "delete";
 
 /**
  * Payload received when a realtime event occurs.
-g */
+ *
+ * @typeParam T - The entity type for the data field. Defaults to `any`.
+ */
 export interface RealtimeEvent<T = any> {
   /** The type of change that occurred */
   type: RealtimeEventType;
@@ -19,6 +21,8 @@ export interface RealtimeEvent<T = any> {
 
 /**
  * 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;
 
@@ -42,18 +46,34 @@ export interface DeleteManyResult {
 
 /**
  * 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 */
+  /** 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 for entity queries. Prefix with `-` for descending order.
+ * 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)
@@ -62,14 +82,16 @@ export type SortField<T> =
 
 /**
  * Registry mapping entity names to their TypeScript types.
- * Augmented by `base44 types generate` to enable type-safe entity access.
+ * Augment this interface to enable type-safe entity access.
  */
 export interface EntityTypeRegistry {}
 
 /**
  * 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<T = any> {
   /**
@@ -80,11 +102,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
@@ -126,14 +149,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
@@ -318,7 +342,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
@@ -327,7 +351,7 @@ export interface EntityHandler<T = any> {
    *   const file = event.target.files?.[0];
    *   if (file) {
    *     const result = await base44.entities.MyEntity.importEntities(file);
-   *     if (result.status === 'success') {
+   *     if (result.status === 'success' && result.output) {
    *       console.log(`Imported ${result.output?.length} records`);
    *     }
    *   }
@@ -387,9 +411,6 @@ type DynamicEntitiesModule = {
  * Entities are accessed dynamically using the pattern:
  * `base44.entities.EntityName.method()`
  *
- * When {@link EntityTypeRegistry} is augmented (via `base44 types generate`),
- * entity access becomes type-safe with autocomplete and type checking.
- *
  * This module is available to use with a client in all three authentication modes:
  *
  * - **Anonymous or User authentication** (`base44.entities`): Access is scoped to the current user's permissions. Anonymous users can only access public entities, while authenticated users can access entities they have permission to view or modify.

src/modules/functions.types.ts

@@ -1,6 +1,6 @@
 /**
  * Registry of function names.
- * Augmented by `base44 types generate` to enable autocomplete for function names.
+ * Augment this interface to enable autocomplete for function names.
  */
 export interface FunctionNameRegistry {}