remult 0.23.0-exp.14 → 0.23.0-exp.16

package/esm/index.d.ts

@@ -1,5 +1,5 @@
 import type { ClassType } from './classType';
-export { OmitEB, FieldsMetadata, FieldRef, IdFieldRef, FieldsRef, EntityMetadata, EntityOrderBy, EntityFilter, FindOptions, QueryResult, QueryOptions, Repository, FindFirstOptions, ComparisonValueFilter, ValueFilter, IdFilter, ContainsStringValueFilter, EntityRef, SortSegments, Paginator, LiveQuery, LiveQueryChangeInfo, Subscribable, RefSubscriber, RefSubscriberBase, RelationOptions, RelationOptionsBase, ObjectMembersOnly, MembersToInclude, RepositoryRelations, EntityIdFields, ClassFieldDecorator as MemberDecorator, ClassFieldDecoratorContextStub, } from './src/remult3/remult3';
+export { OmitEB, FieldsMetadata, FieldRef, IdFieldRef, FieldsRef, EntityMetadata, EntityOrderBy, EntityFilter, FindOptions, QueryResult, QueryOptions, Repository, FindFirstOptions, ComparisonValueFilter, ValueFilter, IdFilter, ContainsStringValueFilter, EntityRef, SortSegments, Paginator, LiveQuery, LiveQueryChangeInfo, Subscribable, RefSubscriber, RefSubscriberBase, RelationOptions, ObjectMembersOnly, MembersToInclude, RepositoryRelations, EntityIdFields, ClassFieldDecorator as MemberDecorator, ClassFieldDecoratorContextStub, } from './src/remult3/remult3';
 export { EntityBase, ControllerBase, FieldType, getFields, ValueListFieldType, getValueList, ValueListFieldOptions, ValueListInfo, CaptionTransformer, } from './src/remult3/RepositoryImplementation';
 export { Entity } from './src/remult3/entity';
 export { getEntityRef } from './src/remult3/getEntityRef';

package/esm/src/column-interfaces.d.ts

@@ -69,8 +69,20 @@ export interface FieldOptions<entityType = any, valueType = any> {
     defaultValue?: (entity: entityType) => valueType | Promise<valueType>;
     /** The html input type for this field */
     inputType?: string;
-    /** Determines if the referenced entity will be loaded immediately or on demand.
-     * @see[Lazy loading of related entities](http://remult.dev/docs/lazy-loading-of-related-entities.html)
+    /**
+     * @deprecated The 'lazy' option is deprecated and will be removed in future versions.
+     * Use 'Relations.toOne' instead.
+     *
+     * Example usage:
+     * ```
+     * // Deprecated usage with 'lazy' option
+     * @Field(() => Customer, { lazy: true })
+     * customer?: Customer;
+     *
+     * // Preferred usage with 'Relations.toOne'
+     * @Relations.toOne(() => Customer)
+     * customer?: Customer;
+     * ```
      */
     lazy?: boolean;
     /** The value type for this field */

package/esm/src/remult3/Fields.d.ts

@@ -21,15 +21,128 @@ export declare class Fields {
     static boolean<entityType = any>(...options: (FieldOptions<entityType, boolean> | ((options: FieldOptions<entityType, boolean>, remult: Remult) => void))[]): ClassFieldDecorator<entityType, boolean | undefined>;
 }
 export declare class Relations {
-    /** A to one relation with an automatically generated field */
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * If no field or fields are provided, it will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options (Optional): An object containing options for configuring the to-one relation.
+     * @returns A decorator function to apply the to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer)
+     * customer?: Customer;
+     * ```
+     */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options?: FieldOptions<entityType, toEntityType> & Pick<RelationOptions<entityType, toEntityType, any, any>, 'defaultIncluded'>): ClassFieldDecorator<entityType, toEntityType | undefined>;
-    /** A to one relation with fields defined in the second parameter */
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * If no `fieldInMyEntity` is provided, this overload will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param fieldInMyEntity (Optional): The field in the current entity that represents the relation.
+     *                        Use this if you want to specify a custom field name for the relation.
+     * @returns A decorator function to apply the to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer)
+     * customer?: Customer;
+     * ```
+     */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
-    /** A to one relation with fields defined in the field/fields parameter */
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * This overload allows you to define the relation using options.
+     * If no field or fields are provided, it will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options An object containing options for configuring the to-one relation.
+     *                - field (Optional): The name of the field in the related entity that corresponds to this relation.
+     * @returns A decorator function to apply the virtual to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer, {
+     *   field: "customerId",
+     * })
+     * customer?: Customer;
+     * ```
+     */
+    static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * If no field or fields are provided, it will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options An object containing options for configuring the to-one relation.
+     *                - fields (Optional): An object specifying custom field names for the relation.
+     * @returns A decorator function to apply the virtual to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer, {
+     *   fields: {
+     *     customerId: "id",
+     *   },
+     * })
+     * customer?: Customer;
+     * ```
+     */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'field'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
     /** A to one relation with fields defined in the field/fields parameter */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'fields'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
+    /**
+     * Define a toMany relation between entities, indicating a one-to-many relationship.
+     * This method allows you to establish a relationship where one entity can have multiple related entities.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param fieldInToEntity (Optional) The field in the target entity that represents the relation.
+     *                       Use this if you want to specify a custom field name for the relation.
+     * @returns A decorator function to apply the toMany relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toMany(() => Order)
+     * orders?: Order[];
+     *
+     * // or with a custom field name:
+     * @Relations.toMany(() => Order, "customerId")
+     * orders?: Order[];
+     * ```
+     */
     static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInToEntity?: keyof toEntityType): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
+    /**
+     * Define a toMany relation between entities, indicating a one-to-many relationship.
+     * This method allows you to establish a relationship where one entity can have multiple related entities.
+     * You can also specify various options to customize the relation and control related data retrieval.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options An object containing options for configuring the toMany relation.
+     *                - field (Optional): The field in the target entity that represents the relation.
+     *                  Use this if you want to specify a custom field name for the relation.
+     *                - findOptions (Optional): Customize the options for finding related entities.
+     *                  You can set limits, order, where conditions, and more.
+     * @returns A decorator function to apply the toMany relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toMany(() => Order, {
+     *   field: "customerOrders",
+     *   findOptions: {
+     *     limit: 10,
+     *     orderBy: { amount: "desc" },
+     *     where: { completed: true },
+     *   },
+     * })
+     * orders?: Order[];
+     * ```
+     */
     static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: RelationOptions<entityType, toEntityType, toEntityType, FindOptions<toEntityType>>): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
 }
 /**Decorates fields that should be used as fields.

package/esm/src/remult3/RepositoryImplementation.d.ts

@@ -105,7 +105,7 @@ declare abstract class rowHelperBase<T> {
     __validateEntity(): Promise<void>;
     __performColumnAndEntityValidations(): Promise<void>;
     toApiJson(includeRelatedEntities?: boolean): any;
-    _updateEntityBasedOnApi(body: any): Promise<void>;
+    _updateEntityBasedOnApi(body: any, ignoreApiAllowed?: boolean): Promise<void>;
 }
 export declare class rowHelperImplementation<T> extends rowHelperBase<T> implements EntityRef<T> {
     private info;

package/esm/src/remult3/RepositoryImplementation.js

@@ -999,7 +999,9 @@ class rowHelperBase {
                 if (val !== undefined && val !== null)
                     val = col.valueConverter.fromJson(JSON.parse(JSON.stringify(val)));
             }
-            d[col.key] = val;
+            const rel = getRelationInfo(col);
+            if (!rel || rel.type === 'reference')
+                d[col.key] = val;
         }
         return d;
     }
@@ -1062,13 +1064,14 @@ class rowHelperBase {
         }
         return result;
     }
-    async _updateEntityBasedOnApi(body) {
+    async _updateEntityBasedOnApi(body, ignoreApiAllowed = false) {
         let keys = Object.keys(body);
         for (const col of this.columnsInfo) {
             if (keys.includes(col.key))
                 if (col.includeInApi === undefined ||
                     this.remult.isAllowed(col.includeInApi)) {
                     if (!this.remult ||
+                        ignoreApiAllowed ||
                         col.allowApiUpdate === undefined ||
                         this.remult.isAllowedForInstance(this.instance, col.allowApiUpdate)) {
                         let lu = this.lookups.get(col.key);

package/esm/src/remult3/remult3.d.ts

@@ -312,7 +312,7 @@ export declare type EntityOrderBy<entityType> = {
 export declare type EntityFilter<entityType> = {
     [Properties in keyof Partial<OmitEB<entityType>>]?: (Partial<OmitEB<entityType>>[Properties] extends number | Date | undefined ? ComparisonValueFilter<Partial<OmitEB<entityType>>[Properties]> : Partial<OmitEB<entityType>>[Properties] extends string | undefined ? ContainsStringValueFilter & ComparisonValueFilter<string> : Partial<OmitEB<entityType>>[Properties] extends boolean | undefined ? ValueFilter<boolean> : Partial<OmitEB<entityType>>[Properties] extends {
         id?: string | number;
-    } | undefined ? IdFilter<Partial<OmitEB<entityType>>[Properties]> : ValueFilter<Partial<OmitEB<entityType>>[Properties]>) & ContainsStringValueFilter;
+    } | undefined ? IdFilter<Partial<OmitEB<entityType>>[Properties]> : ValueFilter<Partial<OmitEB<entityType>>[Properties]>) | ContainsStringValueFilter;
 } & {
     $or?: EntityFilter<entityType>[];
     $and?: EntityFilter<entityType>[];
@@ -342,7 +342,46 @@ export type IdFilter<valueType> = ValueFilter<valueType> | {
     } ? number : string>;
 };
 export interface LoadOptions<entityType> {
+    /**
+     * @deprecated The 'load' option is deprecated and will be removed in future versions.
+     * Use 'Relations.toOne' along with the 'include' option instead.
+     *
+     * Example usage:
+     * ```
+     * // Deprecated usage with 'load' option
+     * await remult.repo(Order).find({
+     *   load: (o) => [o.customer],
+     * });
+     *
+     *
+     * // Preferred usage with 'Relations.toOne' and 'include' option
+     * await remult.repo(Order).find({
+     *   include: { customer: true },
+     * });
+     * ```
+     */
     load?: (entity: FieldsMetadata<entityType>) => FieldMetadata[];
+    /**
+     * An option used in the `find` and `findFirst` methods to specify which related entities should be included
+     * when querying the source entity. It allows you to eagerly load related data to avoid N+1 query problems.
+     *
+     * @param include An object specifying the related entities to include, their options, and filtering criteria.
+     *
+     * Example usage:
+     * ```
+     * const orders = await customerRepo.find({
+     *   include: {
+     *     // Include the 'tags' relation for each customer.
+     *     tags: true,
+     *   },
+     * });
+     * ```
+     * In this example, the `tags` relation for each customer will be loaded and included in the query result.
+     *
+     * @see {@link Relations.toMany}
+     * @see {@link Relations.toOne}
+     * @see {@link RelationOptions}
+     */
     include?: MembersToInclude<entityType>;
 }
 export interface FindOptionsBase<entityType> extends LoadOptions<entityType> {
@@ -413,14 +452,34 @@ export interface RelationInfo {
     toType: () => any;
     type: 'reference' | 'toOne' | 'toMany';
 }
+/**
+ * Options for configuring a relation between entities.
+ *
+ * @template fromEntity The type of the source entity (the entity defining the relation).
+ * @template toEntity The type of the target entity (the related entity).
+ * @template matchIdEntity The type used for matching IDs in the relation.
+ * @template optionsType The type of find options to apply to the relation (default is FindOptionsBase<toEntity>).
+ */
 export type RelationOptions<fromEntity, toEntity, matchIdEntity, optionsType extends FindOptionsBase<toEntity> = FindOptionsBase<toEntity>> = {
     fields?: {
         [K in keyof toEntity]?: keyof fromEntity;
     };
+    /**
+     * The name of the field for this relation.
+     */
     field?: keyof matchIdEntity;
-} & RelationOptionsBase<fromEntity, toEntity, optionsType>;
-export type RelationOptionsBase<fromEntity, toEntity, optionsType extends LoadOptions<toEntity> = LoadOptions<toEntity>> = {
+    /**
+     * Find options to apply to the relation when fetching related entities.
+     * You can specify a predefined set of find options or provide a function that takes the source entity
+     * and returns find options dynamically.
+     * These options allow you to customize how related entities are retrieved.
+     */
     findOptions?: optionsType | ((entity: fromEntity) => optionsType);
+    /**
+     * Determines whether the relation should be included by default when querying the source entity.
+     * When set to true, related entities will be automatically included when querying the source entity.
+     * If false or not specified, related entities will need to be explicitly included using the `include` option.
+     */
     defaultIncluded?: boolean;
 } & Pick<FieldOptions, 'caption'>;
 export type ObjectMembersOnly<T> = {

package/esm/src/remult3/remult3.js

@@ -1 +1,3 @@
 export {};
+//p1 - include relations in the api docs
+//p1 - include Relation options in the api docs

package/esm/src/server-action.js

@@ -268,7 +268,7 @@ export function BackendMethod(options) {
                                 id: defs.getOriginalId(),
                             },
                         }, baseUrl, http);
-                        await defs._updateEntityBasedOnApi(r.rowInfo.data);
+                        await defs._updateEntityBasedOnApi(r.rowInfo.data, true);
                         return r.result;
                     }
                     catch (err) {

package/index.d.ts

@@ -1,5 +1,5 @@
 import type { ClassType } from './classType';
-export { OmitEB, FieldsMetadata, FieldRef, IdFieldRef, FieldsRef, EntityMetadata, EntityOrderBy, EntityFilter, FindOptions, QueryResult, QueryOptions, Repository, FindFirstOptions, ComparisonValueFilter, ValueFilter, IdFilter, ContainsStringValueFilter, EntityRef, SortSegments, Paginator, LiveQuery, LiveQueryChangeInfo, Subscribable, RefSubscriber, RefSubscriberBase, RelationOptions, RelationOptionsBase, ObjectMembersOnly, MembersToInclude, RepositoryRelations, EntityIdFields, ClassFieldDecorator as MemberDecorator, ClassFieldDecoratorContextStub, } from './src/remult3/remult3';
+export { OmitEB, FieldsMetadata, FieldRef, IdFieldRef, FieldsRef, EntityMetadata, EntityOrderBy, EntityFilter, FindOptions, QueryResult, QueryOptions, Repository, FindFirstOptions, ComparisonValueFilter, ValueFilter, IdFilter, ContainsStringValueFilter, EntityRef, SortSegments, Paginator, LiveQuery, LiveQueryChangeInfo, Subscribable, RefSubscriber, RefSubscriberBase, RelationOptions, ObjectMembersOnly, MembersToInclude, RepositoryRelations, EntityIdFields, ClassFieldDecorator as MemberDecorator, ClassFieldDecoratorContextStub, } from './src/remult3/remult3';
 export { EntityBase, ControllerBase, FieldType, getFields, ValueListFieldType, getValueList, ValueListFieldOptions, ValueListInfo, CaptionTransformer, } from './src/remult3/RepositoryImplementation';
 export { Entity } from './src/remult3/entity';
 export { getEntityRef } from './src/remult3/getEntityRef';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "remult",
-    "version": "0.23.0-exp.14",
+    "version": "0.23.0-exp.16",
     "description": "A CRUD framework for full-stack TypeScript",
     "types": "index.d.ts",
     "module": "esm/index.js",

package/src/column-interfaces.d.ts

@@ -69,8 +69,20 @@ export interface FieldOptions<entityType = any, valueType = any> {
     defaultValue?: (entity: entityType) => valueType | Promise<valueType>;
     /** The html input type for this field */
     inputType?: string;
-    /** Determines if the referenced entity will be loaded immediately or on demand.
-     * @see[Lazy loading of related entities](http://remult.dev/docs/lazy-loading-of-related-entities.html)
+    /**
+     * @deprecated The 'lazy' option is deprecated and will be removed in future versions.
+     * Use 'Relations.toOne' instead.
+     *
+     * Example usage:
+     * ```
+     * // Deprecated usage with 'lazy' option
+     * @Field(() => Customer, { lazy: true })
+     * customer?: Customer;
+     *
+     * // Preferred usage with 'Relations.toOne'
+     * @Relations.toOne(() => Customer)
+     * customer?: Customer;
+     * ```
      */
     lazy?: boolean;
     /** The value type for this field */

package/src/remult3/Fields.d.ts

@@ -21,15 +21,128 @@ export declare class Fields {
     static boolean<entityType = any>(...options: (FieldOptions<entityType, boolean> | ((options: FieldOptions<entityType, boolean>, remult: Remult) => void))[]): ClassFieldDecorator<entityType, boolean | undefined>;
 }
 export declare class Relations {
-    /** A to one relation with an automatically generated field */
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * If no field or fields are provided, it will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options (Optional): An object containing options for configuring the to-one relation.
+     * @returns A decorator function to apply the to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer)
+     * customer?: Customer;
+     * ```
+     */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options?: FieldOptions<entityType, toEntityType> & Pick<RelationOptions<entityType, toEntityType, any, any>, 'defaultIncluded'>): ClassFieldDecorator<entityType, toEntityType | undefined>;
-    /** A to one relation with fields defined in the second parameter */
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * If no `fieldInMyEntity` is provided, this overload will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param fieldInMyEntity (Optional): The field in the current entity that represents the relation.
+     *                        Use this if you want to specify a custom field name for the relation.
+     * @returns A decorator function to apply the to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer)
+     * customer?: Customer;
+     * ```
+     */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
-    /** A to one relation with fields defined in the field/fields parameter */
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * This overload allows you to define the relation using options.
+     * If no field or fields are provided, it will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options An object containing options for configuring the to-one relation.
+     *                - field (Optional): The name of the field in the related entity that corresponds to this relation.
+     * @returns A decorator function to apply the virtual to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer, {
+     *   field: "customerId",
+     * })
+     * customer?: Customer;
+     * ```
+     */
+    static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
+    /**
+     * Define a to-one relation between entities, indicating a one-to-one relationship.
+     * If no field or fields are provided, it will automatically create a field in the database
+     * to represent the relation.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options An object containing options for configuring the to-one relation.
+     *                - fields (Optional): An object specifying custom field names for the relation.
+     * @returns A decorator function to apply the virtual to-one relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toOne(() => Customer, {
+     *   fields: {
+     *     customerId: "id",
+     *   },
+     * })
+     * customer?: Customer;
+     * ```
+     */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'field'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
     /** A to one relation with fields defined in the field/fields parameter */
     static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'fields'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
+    /**
+     * Define a toMany relation between entities, indicating a one-to-many relationship.
+     * This method allows you to establish a relationship where one entity can have multiple related entities.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param fieldInToEntity (Optional) The field in the target entity that represents the relation.
+     *                       Use this if you want to specify a custom field name for the relation.
+     * @returns A decorator function to apply the toMany relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toMany(() => Order)
+     * orders?: Order[];
+     *
+     * // or with a custom field name:
+     * @Relations.toMany(() => Order, "customerId")
+     * orders?: Order[];
+     * ```
+     */
     static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInToEntity?: keyof toEntityType): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
+    /**
+     * Define a toMany relation between entities, indicating a one-to-many relationship.
+     * This method allows you to establish a relationship where one entity can have multiple related entities.
+     * You can also specify various options to customize the relation and control related data retrieval.
+     *
+     * @param toEntityType A function that returns the target entity type.
+     * @param options An object containing options for configuring the toMany relation.
+     *                - field (Optional): The field in the target entity that represents the relation.
+     *                  Use this if you want to specify a custom field name for the relation.
+     *                - findOptions (Optional): Customize the options for finding related entities.
+     *                  You can set limits, order, where conditions, and more.
+     * @returns A decorator function to apply the toMany relation to an entity field.
+     *
+     * Example usage:
+     * ```
+     * @Relations.toMany(() => Order, {
+     *   field: "customerOrders",
+     *   findOptions: {
+     *     limit: 10,
+     *     orderBy: { amount: "desc" },
+     *     where: { completed: true },
+     *   },
+     * })
+     * orders?: Order[];
+     * ```
+     */
     static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: RelationOptions<entityType, toEntityType, toEntityType, FindOptions<toEntityType>>): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
 }
 /**Decorates fields that should be used as fields.

package/src/remult3/RepositoryImplementation.d.ts

@@ -105,7 +105,7 @@ declare abstract class rowHelperBase<T> {
     __validateEntity(): Promise<void>;
     __performColumnAndEntityValidations(): Promise<void>;
     toApiJson(includeRelatedEntities?: boolean): any;
-    _updateEntityBasedOnApi(body: any): Promise<void>;
+    _updateEntityBasedOnApi(body: any, ignoreApiAllowed?: boolean): Promise<void>;
 }
 export declare class rowHelperImplementation<T> extends rowHelperBase<T> implements EntityRef<T> {
     private info;

package/src/remult3/RepositoryImplementation.js

@@ -1554,7 +1554,9 @@ var rowHelperBase = /** @class */ (function () {
                     if (val !== undefined && val !== null)
                         val = col.valueConverter.fromJson(JSON.parse(JSON.stringify(val)));
                 }
-                d[col.key] = val;
+                var rel = (0, relationInfoMember_1.getRelationInfo)(col);
+                if (!rel || rel.type === 'reference')
+                    d[col.key] = val;
             }
         }
         catch (e_25_1) { e_25 = { error: e_25_1 }; }
@@ -1667,7 +1669,8 @@ var rowHelperBase = /** @class */ (function () {
         }
         return result;
     };
-    rowHelperBase.prototype._updateEntityBasedOnApi = function (body) {
+    rowHelperBase.prototype._updateEntityBasedOnApi = function (body, ignoreApiAllowed) {
+        if (ignoreApiAllowed === void 0) { ignoreApiAllowed = false; }
         return tslib_1.__awaiter(this, void 0, void 0, function () {
             var keys, _a, _b, col, lu;
             var e_27, _c;
@@ -1682,6 +1685,7 @@ var rowHelperBase = /** @class */ (function () {
                                     if (col.includeInApi === undefined ||
                                         this.remult.isAllowed(col.includeInApi)) {
                                         if (!this.remult ||
+                                            ignoreApiAllowed ||
                                             col.allowApiUpdate === undefined ||
                                             this.remult.isAllowedForInstance(this.instance, col.allowApiUpdate)) {
                                             lu = this.lookups.get(col.key);

package/src/remult3/remult3.d.ts

@@ -312,7 +312,7 @@ export declare type EntityOrderBy<entityType> = {
 export declare type EntityFilter<entityType> = {
     [Properties in keyof Partial<OmitEB<entityType>>]?: (Partial<OmitEB<entityType>>[Properties] extends number | Date | undefined ? ComparisonValueFilter<Partial<OmitEB<entityType>>[Properties]> : Partial<OmitEB<entityType>>[Properties] extends string | undefined ? ContainsStringValueFilter & ComparisonValueFilter<string> : Partial<OmitEB<entityType>>[Properties] extends boolean | undefined ? ValueFilter<boolean> : Partial<OmitEB<entityType>>[Properties] extends {
         id?: string | number;
-    } | undefined ? IdFilter<Partial<OmitEB<entityType>>[Properties]> : ValueFilter<Partial<OmitEB<entityType>>[Properties]>) & ContainsStringValueFilter;
+    } | undefined ? IdFilter<Partial<OmitEB<entityType>>[Properties]> : ValueFilter<Partial<OmitEB<entityType>>[Properties]>) | ContainsStringValueFilter;
 } & {
     $or?: EntityFilter<entityType>[];
     $and?: EntityFilter<entityType>[];
@@ -342,7 +342,46 @@ export type IdFilter<valueType> = ValueFilter<valueType> | {
     } ? number : string>;
 };
 export interface LoadOptions<entityType> {
+    /**
+     * @deprecated The 'load' option is deprecated and will be removed in future versions.
+     * Use 'Relations.toOne' along with the 'include' option instead.
+     *
+     * Example usage:
+     * ```
+     * // Deprecated usage with 'load' option
+     * await remult.repo(Order).find({
+     *   load: (o) => [o.customer],
+     * });
+     *
+     *
+     * // Preferred usage with 'Relations.toOne' and 'include' option
+     * await remult.repo(Order).find({
+     *   include: { customer: true },
+     * });
+     * ```
+     */
     load?: (entity: FieldsMetadata<entityType>) => FieldMetadata[];
+    /**
+     * An option used in the `find` and `findFirst` methods to specify which related entities should be included
+     * when querying the source entity. It allows you to eagerly load related data to avoid N+1 query problems.
+     *
+     * @param include An object specifying the related entities to include, their options, and filtering criteria.
+     *
+     * Example usage:
+     * ```
+     * const orders = await customerRepo.find({
+     *   include: {
+     *     // Include the 'tags' relation for each customer.
+     *     tags: true,
+     *   },
+     * });
+     * ```
+     * In this example, the `tags` relation for each customer will be loaded and included in the query result.
+     *
+     * @see {@link Relations.toMany}
+     * @see {@link Relations.toOne}
+     * @see {@link RelationOptions}
+     */
     include?: MembersToInclude<entityType>;
 }
 export interface FindOptionsBase<entityType> extends LoadOptions<entityType> {
@@ -413,14 +452,34 @@ export interface RelationInfo {
     toType: () => any;
     type: 'reference' | 'toOne' | 'toMany';
 }
+/**
+ * Options for configuring a relation between entities.
+ *
+ * @template fromEntity The type of the source entity (the entity defining the relation).
+ * @template toEntity The type of the target entity (the related entity).
+ * @template matchIdEntity The type used for matching IDs in the relation.
+ * @template optionsType The type of find options to apply to the relation (default is FindOptionsBase<toEntity>).
+ */
 export type RelationOptions<fromEntity, toEntity, matchIdEntity, optionsType extends FindOptionsBase<toEntity> = FindOptionsBase<toEntity>> = {
     fields?: {
         [K in keyof toEntity]?: keyof fromEntity;
     };
+    /**
+     * The name of the field for this relation.
+     */
     field?: keyof matchIdEntity;
-} & RelationOptionsBase<fromEntity, toEntity, optionsType>;
-export type RelationOptionsBase<fromEntity, toEntity, optionsType extends LoadOptions<toEntity> = LoadOptions<toEntity>> = {
+    /**
+     * Find options to apply to the relation when fetching related entities.
+     * You can specify a predefined set of find options or provide a function that takes the source entity
+     * and returns find options dynamically.
+     * These options allow you to customize how related entities are retrieved.
+     */
     findOptions?: optionsType | ((entity: fromEntity) => optionsType);
+    /**
+     * Determines whether the relation should be included by default when querying the source entity.
+     * When set to true, related entities will be automatically included when querying the source entity.
+     * If false or not specified, related entities will need to be explicitly included using the `include` option.
+     */
     defaultIncluded?: boolean;
 } & Pick<FieldOptions, 'caption'>;
 export type ObjectMembersOnly<T> = {

package/src/remult3/remult3.js

@@ -1,2 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+//p1 - include relations in the api docs
+//p1 - include Relation options in the api docs

package/src/server-action.js

@@ -440,7 +440,7 @@ function BackendMethod(options) {
                                     http])];
                             case 4:
                                 r = _h.sent();
-                                return [4 /*yield*/, defs._updateEntityBasedOnApi(r.rowInfo.data)];
+                                return [4 /*yield*/, defs._updateEntityBasedOnApi(r.rowInfo.data, true)];
                             case 5:
                                 _h.sent();
                                 return [2 /*return*/, r.result];