remult 0.23.0-exp.15 → 0.23.0-exp.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/esm/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { ClassType } from './classType';
2
- 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';
2
+ 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';
3
3
  export { EntityBase, ControllerBase, FieldType, getFields, ValueListFieldType, getValueList, ValueListFieldOptions, ValueListInfo, CaptionTransformer, } from './src/remult3/RepositoryImplementation';
4
4
  export { Entity } from './src/remult3/entity';
5
5
  export { getEntityRef } from './src/remult3/getEntityRef';
@@ -69,8 +69,20 @@ export interface FieldOptions<entityType = any, valueType = any> {
69
69
  defaultValue?: (entity: entityType) => valueType | Promise<valueType>;
70
70
  /** The html input type for this field */
71
71
  inputType?: string;
72
- /** Determines if the referenced entity will be loaded immediately or on demand.
73
- * @see[Lazy loading of related entities](http://remult.dev/docs/lazy-loading-of-related-entities.html)
72
+ /**
73
+ * @deprecated The 'lazy' option is deprecated and will be removed in future versions.
74
+ * Use 'Relations.toOne' instead.
75
+ *
76
+ * Example usage:
77
+ * ```
78
+ * // Deprecated usage with 'lazy' option
79
+ * @Field(() => Customer, { lazy: true })
80
+ * customer?: Customer;
81
+ *
82
+ * // Preferred usage with 'Relations.toOne'
83
+ * @Relations.toOne(() => Customer)
84
+ * customer?: Customer;
85
+ * ```
74
86
  */
75
87
  lazy?: boolean;
76
88
  /** The value type for this field */
@@ -21,15 +21,128 @@ export declare class Fields {
21
21
  static boolean<entityType = any>(...options: (FieldOptions<entityType, boolean> | ((options: FieldOptions<entityType, boolean>, remult: Remult) => void))[]): ClassFieldDecorator<entityType, boolean | undefined>;
22
22
  }
23
23
  export declare class Relations {
24
- /** A to one relation with an automatically generated field */
24
+ /**
25
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
26
+ * If no field or fields are provided, it will automatically create a field in the database
27
+ * to represent the relation.
28
+ *
29
+ * @param toEntityType A function that returns the target entity type.
30
+ * @param options (Optional): An object containing options for configuring the to-one relation.
31
+ * @returns A decorator function to apply the to-one relation to an entity field.
32
+ *
33
+ * Example usage:
34
+ * ```
35
+ * @Relations.toOne(() => Customer)
36
+ * customer?: Customer;
37
+ * ```
38
+ */
25
39
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options?: FieldOptions<entityType, toEntityType> & Pick<RelationOptions<entityType, toEntityType, any, any>, 'defaultIncluded'>): ClassFieldDecorator<entityType, toEntityType | undefined>;
26
- /** A to one relation with fields defined in the second parameter */
40
+ /**
41
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
42
+ * If no `fieldInMyEntity` is provided, this overload will automatically create a field in the database
43
+ * to represent the relation.
44
+ *
45
+ * @param toEntityType A function that returns the target entity type.
46
+ * @param fieldInMyEntity (Optional): The field in the current entity that represents the relation.
47
+ * Use this if you want to specify a custom field name for the relation.
48
+ * @returns A decorator function to apply the to-one relation to an entity field.
49
+ *
50
+ * Example usage:
51
+ * ```
52
+ * @Relations.toOne(() => Customer)
53
+ * customer?: Customer;
54
+ * ```
55
+ */
27
56
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
28
- /** A to one relation with fields defined in the field/fields parameter */
57
+ /**
58
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
59
+ * This overload allows you to define the relation using options.
60
+ * If no field or fields are provided, it will automatically create a field in the database
61
+ * to represent the relation.
62
+ *
63
+ * @param toEntityType A function that returns the target entity type.
64
+ * @param options An object containing options for configuring the to-one relation.
65
+ * - field (Optional): The name of the field in the related entity that corresponds to this relation.
66
+ * @returns A decorator function to apply the virtual to-one relation to an entity field.
67
+ *
68
+ * Example usage:
69
+ * ```
70
+ * @Relations.toOne(() => Customer, {
71
+ * field: "customerId",
72
+ * })
73
+ * customer?: Customer;
74
+ * ```
75
+ */
76
+ static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
77
+ /**
78
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
79
+ * If no field or fields are provided, it will automatically create a field in the database
80
+ * to represent the relation.
81
+ *
82
+ * @param toEntityType A function that returns the target entity type.
83
+ * @param options An object containing options for configuring the to-one relation.
84
+ * - fields (Optional): An object specifying custom field names for the relation.
85
+ * @returns A decorator function to apply the virtual to-one relation to an entity field.
86
+ *
87
+ * Example usage:
88
+ * ```
89
+ * @Relations.toOne(() => Customer, {
90
+ * fields: {
91
+ * customerId: "id",
92
+ * },
93
+ * })
94
+ * customer?: Customer;
95
+ * ```
96
+ */
29
97
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'field'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
30
98
  /** A to one relation with fields defined in the field/fields parameter */
31
99
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'fields'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
100
+ /**
101
+ * Define a toMany relation between entities, indicating a one-to-many relationship.
102
+ * This method allows you to establish a relationship where one entity can have multiple related entities.
103
+ *
104
+ * @param toEntityType A function that returns the target entity type.
105
+ * @param fieldInToEntity (Optional) The field in the target entity that represents the relation.
106
+ * Use this if you want to specify a custom field name for the relation.
107
+ * @returns A decorator function to apply the toMany relation to an entity field.
108
+ *
109
+ * Example usage:
110
+ * ```
111
+ * @Relations.toMany(() => Order)
112
+ * orders?: Order[];
113
+ *
114
+ * // or with a custom field name:
115
+ * @Relations.toMany(() => Order, "customerId")
116
+ * orders?: Order[];
117
+ * ```
118
+ */
32
119
  static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInToEntity?: keyof toEntityType): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
120
+ /**
121
+ * Define a toMany relation between entities, indicating a one-to-many relationship.
122
+ * This method allows you to establish a relationship where one entity can have multiple related entities.
123
+ * You can also specify various options to customize the relation and control related data retrieval.
124
+ *
125
+ * @param toEntityType A function that returns the target entity type.
126
+ * @param options An object containing options for configuring the toMany relation.
127
+ * - field (Optional): The field in the target entity that represents the relation.
128
+ * Use this if you want to specify a custom field name for the relation.
129
+ * - findOptions (Optional): Customize the options for finding related entities.
130
+ * You can set limits, order, where conditions, and more.
131
+ * @returns A decorator function to apply the toMany relation to an entity field.
132
+ *
133
+ * Example usage:
134
+ * ```
135
+ * @Relations.toMany(() => Order, {
136
+ * field: "customerOrders",
137
+ * findOptions: {
138
+ * limit: 10,
139
+ * orderBy: { amount: "desc" },
140
+ * where: { completed: true },
141
+ * },
142
+ * })
143
+ * orders?: Order[];
144
+ * ```
145
+ */
33
146
  static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: RelationOptions<entityType, toEntityType, toEntityType, FindOptions<toEntityType>>): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
34
147
  }
35
148
  /**Decorates fields that should be used as fields.
@@ -75,10 +75,11 @@ declare abstract class rowHelperBase<T> {
75
75
  protected columnsInfo: FieldOptions[];
76
76
  protected instance: T;
77
77
  protected remult: Remult;
78
+ protected isNewRow: boolean;
78
79
  _error: string;
79
80
  get error(): string;
80
81
  set error(val: string);
81
- constructor(columnsInfo: FieldOptions[], instance: T, remult: Remult);
82
+ constructor(columnsInfo: FieldOptions[], instance: T, remult: Remult, isNewRow: boolean);
82
83
  _subscribers: SubscribableImp;
83
84
  subscribe(listener: RefSubscriber): Unsubscribe;
84
85
  _isLoading: boolean;
@@ -105,7 +106,7 @@ declare abstract class rowHelperBase<T> {
105
106
  __validateEntity(): Promise<void>;
106
107
  __performColumnAndEntityValidations(): Promise<void>;
107
108
  toApiJson(includeRelatedEntities?: boolean): any;
108
- _updateEntityBasedOnApi(body: any): Promise<void>;
109
+ _updateEntityBasedOnApi(body: any, ignoreApiAllowed?: boolean): Promise<void>;
109
110
  }
110
111
  export declare class rowHelperImplementation<T> extends rowHelperBase<T> implements EntityRef<T> {
111
112
  private info;
@@ -789,6 +789,7 @@ class rowHelperBase {
789
789
  columnsInfo;
790
790
  instance;
791
791
  remult;
792
+ isNewRow;
792
793
  _error;
793
794
  get error() {
794
795
  this._subscribers?.reportObserved();
@@ -798,10 +799,11 @@ class rowHelperBase {
798
799
  this._error = val;
799
800
  this._subscribers?.reportChanged();
800
801
  }
801
- constructor(columnsInfo, instance, remult) {
802
+ constructor(columnsInfo, instance, remult, isNewRow) {
802
803
  this.columnsInfo = columnsInfo;
803
804
  this.instance = instance;
804
805
  this.remult = remult;
806
+ this.isNewRow = isNewRow;
805
807
  {
806
808
  let fac = remult;
807
809
  if (fac != null && fac.remultFactory) {
@@ -847,6 +849,8 @@ class rowHelperBase {
847
849
  else if (getRelationInfo(col)?.type === 'toOne') {
848
850
  let hasVal = instance.hasOwnProperty(col.key);
849
851
  let val = instance[col.key];
852
+ if (isNewRow && !val)
853
+ hasVal = false;
850
854
  Object.defineProperty(instance, col.key, {
851
855
  get: () => {
852
856
  return val;
@@ -999,7 +1003,9 @@ class rowHelperBase {
999
1003
  if (val !== undefined && val !== null)
1000
1004
  val = col.valueConverter.fromJson(JSON.parse(JSON.stringify(val)));
1001
1005
  }
1002
- d[col.key] = val;
1006
+ const rel = getRelationInfo(col);
1007
+ if (!rel || rel.type === 'reference')
1008
+ d[col.key] = val;
1003
1009
  }
1004
1010
  return d;
1005
1011
  }
@@ -1062,13 +1068,14 @@ class rowHelperBase {
1062
1068
  }
1063
1069
  return result;
1064
1070
  }
1065
- async _updateEntityBasedOnApi(body) {
1071
+ async _updateEntityBasedOnApi(body, ignoreApiAllowed = false) {
1066
1072
  let keys = Object.keys(body);
1067
1073
  for (const col of this.columnsInfo) {
1068
1074
  if (keys.includes(col.key))
1069
1075
  if (col.includeInApi === undefined ||
1070
1076
  this.remult.isAllowed(col.includeInApi)) {
1071
1077
  if (!this.remult ||
1078
+ ignoreApiAllowed ||
1072
1079
  col.allowApiUpdate === undefined ||
1073
1080
  this.remult.isAllowedForInstance(this.instance, col.allowApiUpdate)) {
1074
1081
  let lu = this.lookups.get(col.key);
@@ -1088,7 +1095,7 @@ export class rowHelperImplementation extends rowHelperBase {
1088
1095
  edp;
1089
1096
  _isNew;
1090
1097
  constructor(info, instance, repository, edp, remult, _isNew) {
1091
- super(info.columnsInfo, instance, remult);
1098
+ super(info.columnsInfo, instance, remult, _isNew);
1092
1099
  this.info = info;
1093
1100
  this.repository = repository;
1094
1101
  this.edp = edp;
@@ -1394,7 +1401,7 @@ export function getControllerRef(container, remultArg) {
1394
1401
  }
1395
1402
  export class controllerRefImpl extends rowHelperBase {
1396
1403
  constructor(columnsInfo, instance, remult) {
1397
- super(columnsInfo, instance, remult);
1404
+ super(columnsInfo, instance, remult, false);
1398
1405
  let _items = [];
1399
1406
  let r = {
1400
1407
  find: (c) => r[typeof c === 'string' ? c : c.key],
@@ -342,7 +342,46 @@ export type IdFilter<valueType> = ValueFilter<valueType> | {
342
342
  } ? number : string>;
343
343
  };
344
344
  export interface LoadOptions<entityType> {
345
+ /**
346
+ * @deprecated The 'load' option is deprecated and will be removed in future versions.
347
+ * Use 'Relations.toOne' along with the 'include' option instead.
348
+ *
349
+ * Example usage:
350
+ * ```
351
+ * // Deprecated usage with 'load' option
352
+ * await remult.repo(Order).find({
353
+ * load: (o) => [o.customer],
354
+ * });
355
+ *
356
+ *
357
+ * // Preferred usage with 'Relations.toOne' and 'include' option
358
+ * await remult.repo(Order).find({
359
+ * include: { customer: true },
360
+ * });
361
+ * ```
362
+ */
345
363
  load?: (entity: FieldsMetadata<entityType>) => FieldMetadata[];
364
+ /**
365
+ * An option used in the `find` and `findFirst` methods to specify which related entities should be included
366
+ * when querying the source entity. It allows you to eagerly load related data to avoid N+1 query problems.
367
+ *
368
+ * @param include An object specifying the related entities to include, their options, and filtering criteria.
369
+ *
370
+ * Example usage:
371
+ * ```
372
+ * const orders = await customerRepo.find({
373
+ * include: {
374
+ * // Include the 'tags' relation for each customer.
375
+ * tags: true,
376
+ * },
377
+ * });
378
+ * ```
379
+ * In this example, the `tags` relation for each customer will be loaded and included in the query result.
380
+ *
381
+ * @see {@link Relations.toMany}
382
+ * @see {@link Relations.toOne}
383
+ * @see {@link RelationOptions}
384
+ */
346
385
  include?: MembersToInclude<entityType>;
347
386
  }
348
387
  export interface FindOptionsBase<entityType> extends LoadOptions<entityType> {
@@ -413,14 +452,34 @@ export interface RelationInfo {
413
452
  toType: () => any;
414
453
  type: 'reference' | 'toOne' | 'toMany';
415
454
  }
455
+ /**
456
+ * Options for configuring a relation between entities.
457
+ *
458
+ * @template fromEntity The type of the source entity (the entity defining the relation).
459
+ * @template toEntity The type of the target entity (the related entity).
460
+ * @template matchIdEntity The type used for matching IDs in the relation.
461
+ * @template optionsType The type of find options to apply to the relation (default is FindOptionsBase<toEntity>).
462
+ */
416
463
  export type RelationOptions<fromEntity, toEntity, matchIdEntity, optionsType extends FindOptionsBase<toEntity> = FindOptionsBase<toEntity>> = {
417
464
  fields?: {
418
465
  [K in keyof toEntity]?: keyof fromEntity;
419
466
  };
467
+ /**
468
+ * The name of the field for this relation.
469
+ */
420
470
  field?: keyof matchIdEntity;
421
- } & RelationOptionsBase<fromEntity, toEntity, optionsType>;
422
- export type RelationOptionsBase<fromEntity, toEntity, optionsType extends LoadOptions<toEntity> = LoadOptions<toEntity>> = {
471
+ /**
472
+ * Find options to apply to the relation when fetching related entities.
473
+ * You can specify a predefined set of find options or provide a function that takes the source entity
474
+ * and returns find options dynamically.
475
+ * These options allow you to customize how related entities are retrieved.
476
+ */
423
477
  findOptions?: optionsType | ((entity: fromEntity) => optionsType);
478
+ /**
479
+ * Determines whether the relation should be included by default when querying the source entity.
480
+ * When set to true, related entities will be automatically included when querying the source entity.
481
+ * If false or not specified, related entities will need to be explicitly included using the `include` option.
482
+ */
424
483
  defaultIncluded?: boolean;
425
484
  } & Pick<FieldOptions, 'caption'>;
426
485
  export type ObjectMembersOnly<T> = {
@@ -1 +1,3 @@
1
1
  export {};
2
+ //p1 - include relations in the api docs
3
+ //p1 - include Relation options in the api docs
@@ -268,7 +268,7 @@ export function BackendMethod(options) {
268
268
  id: defs.getOriginalId(),
269
269
  },
270
270
  }, baseUrl, http);
271
- await defs._updateEntityBasedOnApi(r.rowInfo.data);
271
+ await defs._updateEntityBasedOnApi(r.rowInfo.data, true);
272
272
  return r.result;
273
273
  }
274
274
  catch (err) {
package/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { ClassType } from './classType';
2
- 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';
2
+ 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';
3
3
  export { EntityBase, ControllerBase, FieldType, getFields, ValueListFieldType, getValueList, ValueListFieldOptions, ValueListInfo, CaptionTransformer, } from './src/remult3/RepositoryImplementation';
4
4
  export { Entity } from './src/remult3/entity';
5
5
  export { getEntityRef } from './src/remult3/getEntityRef';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "remult",
3
- "version": "0.23.0-exp.15",
3
+ "version": "0.23.0-exp.17",
4
4
  "description": "A CRUD framework for full-stack TypeScript",
5
5
  "types": "index.d.ts",
6
6
  "module": "esm/index.js",
@@ -69,8 +69,20 @@ export interface FieldOptions<entityType = any, valueType = any> {
69
69
  defaultValue?: (entity: entityType) => valueType | Promise<valueType>;
70
70
  /** The html input type for this field */
71
71
  inputType?: string;
72
- /** Determines if the referenced entity will be loaded immediately or on demand.
73
- * @see[Lazy loading of related entities](http://remult.dev/docs/lazy-loading-of-related-entities.html)
72
+ /**
73
+ * @deprecated The 'lazy' option is deprecated and will be removed in future versions.
74
+ * Use 'Relations.toOne' instead.
75
+ *
76
+ * Example usage:
77
+ * ```
78
+ * // Deprecated usage with 'lazy' option
79
+ * @Field(() => Customer, { lazy: true })
80
+ * customer?: Customer;
81
+ *
82
+ * // Preferred usage with 'Relations.toOne'
83
+ * @Relations.toOne(() => Customer)
84
+ * customer?: Customer;
85
+ * ```
74
86
  */
75
87
  lazy?: boolean;
76
88
  /** The value type for this field */
@@ -21,15 +21,128 @@ export declare class Fields {
21
21
  static boolean<entityType = any>(...options: (FieldOptions<entityType, boolean> | ((options: FieldOptions<entityType, boolean>, remult: Remult) => void))[]): ClassFieldDecorator<entityType, boolean | undefined>;
22
22
  }
23
23
  export declare class Relations {
24
- /** A to one relation with an automatically generated field */
24
+ /**
25
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
26
+ * If no field or fields are provided, it will automatically create a field in the database
27
+ * to represent the relation.
28
+ *
29
+ * @param toEntityType A function that returns the target entity type.
30
+ * @param options (Optional): An object containing options for configuring the to-one relation.
31
+ * @returns A decorator function to apply the to-one relation to an entity field.
32
+ *
33
+ * Example usage:
34
+ * ```
35
+ * @Relations.toOne(() => Customer)
36
+ * customer?: Customer;
37
+ * ```
38
+ */
25
39
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options?: FieldOptions<entityType, toEntityType> & Pick<RelationOptions<entityType, toEntityType, any, any>, 'defaultIncluded'>): ClassFieldDecorator<entityType, toEntityType | undefined>;
26
- /** A to one relation with fields defined in the second parameter */
40
+ /**
41
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
42
+ * If no `fieldInMyEntity` is provided, this overload will automatically create a field in the database
43
+ * to represent the relation.
44
+ *
45
+ * @param toEntityType A function that returns the target entity type.
46
+ * @param fieldInMyEntity (Optional): The field in the current entity that represents the relation.
47
+ * Use this if you want to specify a custom field name for the relation.
48
+ * @returns A decorator function to apply the to-one relation to an entity field.
49
+ *
50
+ * Example usage:
51
+ * ```
52
+ * @Relations.toOne(() => Customer)
53
+ * customer?: Customer;
54
+ * ```
55
+ */
27
56
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
28
- /** A to one relation with fields defined in the field/fields parameter */
57
+ /**
58
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
59
+ * This overload allows you to define the relation using options.
60
+ * If no field or fields are provided, it will automatically create a field in the database
61
+ * to represent the relation.
62
+ *
63
+ * @param toEntityType A function that returns the target entity type.
64
+ * @param options An object containing options for configuring the to-one relation.
65
+ * - field (Optional): The name of the field in the related entity that corresponds to this relation.
66
+ * @returns A decorator function to apply the virtual to-one relation to an entity field.
67
+ *
68
+ * Example usage:
69
+ * ```
70
+ * @Relations.toOne(() => Customer, {
71
+ * field: "customerId",
72
+ * })
73
+ * customer?: Customer;
74
+ * ```
75
+ */
76
+ static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInMyEntity?: keyof entityType): ClassFieldDecorator<entityType, toEntityType | undefined>;
77
+ /**
78
+ * Define a to-one relation between entities, indicating a one-to-one relationship.
79
+ * If no field or fields are provided, it will automatically create a field in the database
80
+ * to represent the relation.
81
+ *
82
+ * @param toEntityType A function that returns the target entity type.
83
+ * @param options An object containing options for configuring the to-one relation.
84
+ * - fields (Optional): An object specifying custom field names for the relation.
85
+ * @returns A decorator function to apply the virtual to-one relation to an entity field.
86
+ *
87
+ * Example usage:
88
+ * ```
89
+ * @Relations.toOne(() => Customer, {
90
+ * fields: {
91
+ * customerId: "id",
92
+ * },
93
+ * })
94
+ * customer?: Customer;
95
+ * ```
96
+ */
29
97
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'field'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
30
98
  /** A to one relation with fields defined in the field/fields parameter */
31
99
  static toOne<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: Omit<RelationOptions<entityType, toEntityType, entityType>, keyof Pick<RelationOptions<entityType, toEntityType, entityType>, 'fields'>>): ClassFieldDecorator<entityType, toEntityType | undefined>;
100
+ /**
101
+ * Define a toMany relation between entities, indicating a one-to-many relationship.
102
+ * This method allows you to establish a relationship where one entity can have multiple related entities.
103
+ *
104
+ * @param toEntityType A function that returns the target entity type.
105
+ * @param fieldInToEntity (Optional) The field in the target entity that represents the relation.
106
+ * Use this if you want to specify a custom field name for the relation.
107
+ * @returns A decorator function to apply the toMany relation to an entity field.
108
+ *
109
+ * Example usage:
110
+ * ```
111
+ * @Relations.toMany(() => Order)
112
+ * orders?: Order[];
113
+ *
114
+ * // or with a custom field name:
115
+ * @Relations.toMany(() => Order, "customerId")
116
+ * orders?: Order[];
117
+ * ```
118
+ */
32
119
  static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, fieldInToEntity?: keyof toEntityType): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
120
+ /**
121
+ * Define a toMany relation between entities, indicating a one-to-many relationship.
122
+ * This method allows you to establish a relationship where one entity can have multiple related entities.
123
+ * You can also specify various options to customize the relation and control related data retrieval.
124
+ *
125
+ * @param toEntityType A function that returns the target entity type.
126
+ * @param options An object containing options for configuring the toMany relation.
127
+ * - field (Optional): The field in the target entity that represents the relation.
128
+ * Use this if you want to specify a custom field name for the relation.
129
+ * - findOptions (Optional): Customize the options for finding related entities.
130
+ * You can set limits, order, where conditions, and more.
131
+ * @returns A decorator function to apply the toMany relation to an entity field.
132
+ *
133
+ * Example usage:
134
+ * ```
135
+ * @Relations.toMany(() => Order, {
136
+ * field: "customerOrders",
137
+ * findOptions: {
138
+ * limit: 10,
139
+ * orderBy: { amount: "desc" },
140
+ * where: { completed: true },
141
+ * },
142
+ * })
143
+ * orders?: Order[];
144
+ * ```
145
+ */
33
146
  static toMany<entityType, toEntityType>(toEntityType: () => ClassType<toEntityType>, options: RelationOptions<entityType, toEntityType, toEntityType, FindOptions<toEntityType>>): ClassFieldDecorator<entityType, toEntityType[] | undefined>;
34
147
  }
35
148
  /**Decorates fields that should be used as fields.
@@ -75,10 +75,11 @@ declare abstract class rowHelperBase<T> {
75
75
  protected columnsInfo: FieldOptions[];
76
76
  protected instance: T;
77
77
  protected remult: Remult;
78
+ protected isNewRow: boolean;
78
79
  _error: string;
79
80
  get error(): string;
80
81
  set error(val: string);
81
- constructor(columnsInfo: FieldOptions[], instance: T, remult: Remult);
82
+ constructor(columnsInfo: FieldOptions[], instance: T, remult: Remult, isNewRow: boolean);
82
83
  _subscribers: SubscribableImp;
83
84
  subscribe(listener: RefSubscriber): Unsubscribe;
84
85
  _isLoading: boolean;
@@ -105,7 +106,7 @@ declare abstract class rowHelperBase<T> {
105
106
  __validateEntity(): Promise<void>;
106
107
  __performColumnAndEntityValidations(): Promise<void>;
107
108
  toApiJson(includeRelatedEntities?: boolean): any;
108
- _updateEntityBasedOnApi(body: any): Promise<void>;
109
+ _updateEntityBasedOnApi(body: any, ignoreApiAllowed?: boolean): Promise<void>;
109
110
  }
110
111
  export declare class rowHelperImplementation<T> extends rowHelperBase<T> implements EntityRef<T> {
111
112
  private info;
@@ -1264,13 +1264,14 @@ function createOldEntity(entity, remult) {
1264
1264
  }
1265
1265
  exports.createOldEntity = createOldEntity;
1266
1266
  var rowHelperBase = /** @class */ (function () {
1267
- function rowHelperBase(columnsInfo, instance, remult) {
1267
+ function rowHelperBase(columnsInfo, instance, remult, isNewRow) {
1268
1268
  var e_21, _a;
1269
1269
  var _this = this;
1270
1270
  var _b;
1271
1271
  this.columnsInfo = columnsInfo;
1272
1272
  this.instance = instance;
1273
1273
  this.remult = remult;
1274
+ this.isNewRow = isNewRow;
1274
1275
  this._isLoading = false;
1275
1276
  this.lookups = new Map();
1276
1277
  this.originalValues = {};
@@ -1320,6 +1321,8 @@ var rowHelperBase = /** @class */ (function () {
1320
1321
  else if (((_b = (0, relationInfoMember_1.getRelationInfo)(col)) === null || _b === void 0 ? void 0 : _b.type) === 'toOne') {
1321
1322
  var hasVal = instance.hasOwnProperty(col.key);
1322
1323
  var val_1 = instance[col.key];
1324
+ if (isNewRow && !val_1)
1325
+ hasVal = false;
1323
1326
  Object.defineProperty(instance, col.key, {
1324
1327
  get: function () {
1325
1328
  return val_1;
@@ -1554,7 +1557,9 @@ var rowHelperBase = /** @class */ (function () {
1554
1557
  if (val !== undefined && val !== null)
1555
1558
  val = col.valueConverter.fromJson(JSON.parse(JSON.stringify(val)));
1556
1559
  }
1557
- d[col.key] = val;
1560
+ var rel = (0, relationInfoMember_1.getRelationInfo)(col);
1561
+ if (!rel || rel.type === 'reference')
1562
+ d[col.key] = val;
1558
1563
  }
1559
1564
  }
1560
1565
  catch (e_25_1) { e_25 = { error: e_25_1 }; }
@@ -1667,7 +1672,8 @@ var rowHelperBase = /** @class */ (function () {
1667
1672
  }
1668
1673
  return result;
1669
1674
  };
1670
- rowHelperBase.prototype._updateEntityBasedOnApi = function (body) {
1675
+ rowHelperBase.prototype._updateEntityBasedOnApi = function (body, ignoreApiAllowed) {
1676
+ if (ignoreApiAllowed === void 0) { ignoreApiAllowed = false; }
1671
1677
  return tslib_1.__awaiter(this, void 0, void 0, function () {
1672
1678
  var keys, _a, _b, col, lu;
1673
1679
  var e_27, _c;
@@ -1682,6 +1688,7 @@ var rowHelperBase = /** @class */ (function () {
1682
1688
  if (col.includeInApi === undefined ||
1683
1689
  this.remult.isAllowed(col.includeInApi)) {
1684
1690
  if (!this.remult ||
1691
+ ignoreApiAllowed ||
1685
1692
  col.allowApiUpdate === undefined ||
1686
1693
  this.remult.isAllowedForInstance(this.instance, col.allowApiUpdate)) {
1687
1694
  lu = this.lookups.get(col.key);
@@ -1714,7 +1721,7 @@ var rowHelperImplementation = /** @class */ (function (_super) {
1714
1721
  tslib_1.__extends(rowHelperImplementation, _super);
1715
1722
  function rowHelperImplementation(info, instance, repository, edp, remult, _isNew) {
1716
1723
  var e_28, _a;
1717
- var _this = _super.call(this, info.columnsInfo, instance, remult) || this;
1724
+ var _this = _super.call(this, info.columnsInfo, instance, remult, _isNew) || this;
1718
1725
  _this.info = info;
1719
1726
  _this.repository = repository;
1720
1727
  _this.edp = edp;
@@ -2364,7 +2371,7 @@ var controllerRefImpl = /** @class */ (function (_super) {
2364
2371
  tslib_1.__extends(controllerRefImpl, _super);
2365
2372
  function controllerRefImpl(columnsInfo, instance, remult) {
2366
2373
  var _a, e_39, _b;
2367
- var _this = _super.call(this, columnsInfo, instance, remult) || this;
2374
+ var _this = _super.call(this, columnsInfo, instance, remult, false) || this;
2368
2375
  var _items = [];
2369
2376
  var r = (_a = {
2370
2377
  find: function (c) {
@@ -342,7 +342,46 @@ export type IdFilter<valueType> = ValueFilter<valueType> | {
342
342
  } ? number : string>;
343
343
  };
344
344
  export interface LoadOptions<entityType> {
345
+ /**
346
+ * @deprecated The 'load' option is deprecated and will be removed in future versions.
347
+ * Use 'Relations.toOne' along with the 'include' option instead.
348
+ *
349
+ * Example usage:
350
+ * ```
351
+ * // Deprecated usage with 'load' option
352
+ * await remult.repo(Order).find({
353
+ * load: (o) => [o.customer],
354
+ * });
355
+ *
356
+ *
357
+ * // Preferred usage with 'Relations.toOne' and 'include' option
358
+ * await remult.repo(Order).find({
359
+ * include: { customer: true },
360
+ * });
361
+ * ```
362
+ */
345
363
  load?: (entity: FieldsMetadata<entityType>) => FieldMetadata[];
364
+ /**
365
+ * An option used in the `find` and `findFirst` methods to specify which related entities should be included
366
+ * when querying the source entity. It allows you to eagerly load related data to avoid N+1 query problems.
367
+ *
368
+ * @param include An object specifying the related entities to include, their options, and filtering criteria.
369
+ *
370
+ * Example usage:
371
+ * ```
372
+ * const orders = await customerRepo.find({
373
+ * include: {
374
+ * // Include the 'tags' relation for each customer.
375
+ * tags: true,
376
+ * },
377
+ * });
378
+ * ```
379
+ * In this example, the `tags` relation for each customer will be loaded and included in the query result.
380
+ *
381
+ * @see {@link Relations.toMany}
382
+ * @see {@link Relations.toOne}
383
+ * @see {@link RelationOptions}
384
+ */
346
385
  include?: MembersToInclude<entityType>;
347
386
  }
348
387
  export interface FindOptionsBase<entityType> extends LoadOptions<entityType> {
@@ -413,14 +452,34 @@ export interface RelationInfo {
413
452
  toType: () => any;
414
453
  type: 'reference' | 'toOne' | 'toMany';
415
454
  }
455
+ /**
456
+ * Options for configuring a relation between entities.
457
+ *
458
+ * @template fromEntity The type of the source entity (the entity defining the relation).
459
+ * @template toEntity The type of the target entity (the related entity).
460
+ * @template matchIdEntity The type used for matching IDs in the relation.
461
+ * @template optionsType The type of find options to apply to the relation (default is FindOptionsBase<toEntity>).
462
+ */
416
463
  export type RelationOptions<fromEntity, toEntity, matchIdEntity, optionsType extends FindOptionsBase<toEntity> = FindOptionsBase<toEntity>> = {
417
464
  fields?: {
418
465
  [K in keyof toEntity]?: keyof fromEntity;
419
466
  };
467
+ /**
468
+ * The name of the field for this relation.
469
+ */
420
470
  field?: keyof matchIdEntity;
421
- } & RelationOptionsBase<fromEntity, toEntity, optionsType>;
422
- export type RelationOptionsBase<fromEntity, toEntity, optionsType extends LoadOptions<toEntity> = LoadOptions<toEntity>> = {
471
+ /**
472
+ * Find options to apply to the relation when fetching related entities.
473
+ * You can specify a predefined set of find options or provide a function that takes the source entity
474
+ * and returns find options dynamically.
475
+ * These options allow you to customize how related entities are retrieved.
476
+ */
423
477
  findOptions?: optionsType | ((entity: fromEntity) => optionsType);
478
+ /**
479
+ * Determines whether the relation should be included by default when querying the source entity.
480
+ * When set to true, related entities will be automatically included when querying the source entity.
481
+ * If false or not specified, related entities will need to be explicitly included using the `include` option.
482
+ */
424
483
  defaultIncluded?: boolean;
425
484
  } & Pick<FieldOptions, 'caption'>;
426
485
  export type ObjectMembersOnly<T> = {
@@ -1,2 +1,4 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ //p1 - include relations in the api docs
4
+ //p1 - include Relation options in the api docs
@@ -440,7 +440,7 @@ function BackendMethod(options) {
440
440
  http])];
441
441
  case 4:
442
442
  r = _h.sent();
443
- return [4 /*yield*/, defs._updateEntityBasedOnApi(r.rowInfo.data)];
443
+ return [4 /*yield*/, defs._updateEntityBasedOnApi(r.rowInfo.data, true)];
444
444
  case 5:
445
445
  _h.sent();
446
446
  return [2 /*return*/, r.result];