remult 0.23.0-exp.18 → 0.23.0-exp.19

package/esm/graphql.js

@@ -794,7 +794,7 @@ export function translateWhereToRestBody(fields, { where }) {
         return undefined;
     const result = {};
     for (const field of fields) {
-        if (field.includedInApi === false)
+        if (field.options.includeInApi === false)
             continue;
         const condition = where[field.key];
         if (condition) {

package/esm/index.d.ts

@@ -30,4 +30,16 @@ export { ValueConverters } from './src/valueConverters';
 export { remult } from './src/remult-proxy';
 export { SubscriptionServer, LiveQueryStorage, StoredQuery, InMemoryLiveQueryStorage, } from './src/live-query/SubscriptionServer';
 export { SubscriptionListener, SubscriptionClientConnection, SubscriptionClient, SubscriptionChannel, LiveQueryChange, Unsubscribe, } from './src/live-query/SubscriptionChannel';
+/**
+ * A convenient shortcut function to quickly obtain a repository for a specific entity type in Remult.
+ *
+ * @param entity The entity class type for which you want to get a repository.
+ * @returns A repository instance for the specified entity type.
+ *
+ * Example usage:
+ * ```ts
+ * await repo(Task).find()
+ * await repo(Customer).insert()
+ * ```
+ */
 export declare function repo<entityType>(entity: ClassType<entityType>): import("./src/remult3/remult3").Repository<entityType>;

package/esm/index.js

@@ -25,6 +25,18 @@ import { remult } from './src/remult-proxy';
 //export { getId } from './src/remult3/getId';
 export { InMemoryLiveQueryStorage, } from './src/live-query/SubscriptionServer';
 export { SubscriptionChannel, } from './src/live-query/SubscriptionChannel';
+/**
+ * A convenient shortcut function to quickly obtain a repository for a specific entity type in Remult.
+ *
+ * @param entity The entity class type for which you want to get a repository.
+ * @returns A repository instance for the specified entity type.
+ *
+ * Example usage:
+ * ```ts
+ * await repo(Task).find()
+ * await repo(Customer).insert()
+ * ```
+ */
 export function repo(entity) {
     return remult.repo(entity);
 }

package/esm/src/CompoundIdField.d.ts

@@ -6,7 +6,7 @@ export declare class CompoundIdField implements FieldMetadata<string> {
     constructor(...columns: FieldMetadata[]);
     apiUpdateAllowed(item: any): boolean;
     displayValue(item: any): string;
-    includedInApi: boolean;
+    includedInApi(item: any): boolean;
     toInput(value: string, inputType?: string): string;
     fromInput(inputValue: string, inputType?: string): string;
     getDbName(): Promise<string>;

package/esm/src/CompoundIdField.js

@@ -9,7 +9,9 @@ export class CompoundIdField {
     displayValue(item) {
         throw new Error('Method not implemented.');
     }
-    includedInApi;
+    includedInApi(item) {
+        throw new Error('Method not implemented.');
+    }
     toInput(value, inputType) {
         throw new Error('Method not implemented.');
     }

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

@@ -1,6 +1,6 @@
 import type { ClassType } from '../classType';
-import type { Allowed, AllowedForInstance } from './context';
-import type { EntityMetadata, FieldRef, LifeCycleEvent, OmitEB } from './remult3/remult3';
+import type { AllowedForInstance } from './context';
+import type { EntityMetadata, FieldRef, LifecycleEvent, OmitEB } from './remult3/remult3';
 export interface FieldOptions<entityType = any, valueType = any> {
     /** A human readable name for the field. Can be used to achieve a consistent caption for a field throughout the app
      * @example
@@ -11,7 +11,7 @@ export interface FieldOptions<entityType = any, valueType = any> {
     allowNull?: boolean;
     /** If this field data is included in the api.
      * @see [allowed](http://remult.dev/docs/allowed.html)*/
-    includeInApi?: Allowed;
+    includeInApi?: AllowedForInstance<entityType>;
     /** If this field data can be updated in the api.
      * @see [allowed](http://remult.dev/docs/allowed.html)*/
     allowApiUpdate?: AllowedForInstance<entityType>;
@@ -37,7 +37,7 @@ export interface FieldOptions<entityType = any, valueType = any> {
      */
     validate?: ((entity: entityType, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>) | ((entity: entityType, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>)[];
     /** Will be fired before this field is saved to the server/database */
-    saving?: (entity: entityType, e: LifeCycleEvent<entityType>, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>;
+    saving?: (entity: entityType, e: LifecycleEvent<entityType>, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>;
     /**  An expression that will determine this fields value on the backend and be provided to the front end*/
     serverExpression?: (entity: entityType) => valueType | Promise<valueType>;
     /** The name of the column in the database that holds the data for this field. If no name is set, the key will be used instead.
@@ -134,7 +134,7 @@ export interface FieldMetadata<valueType = any, entityType = any> {
      */
     displayValue(item: Partial<OmitEB<entityType>>): string;
     apiUpdateAllowed(item?: Partial<OmitEB<entityType>>): boolean;
-    readonly includedInApi: boolean;
+    includedInApi(item?: Partial<OmitEB<entityType>>): boolean;
     /** Adapts the value for usage with html input
      * @example
      * @Fields.dateOnly()

package/esm/src/context.js

@@ -286,3 +286,6 @@ class transactionLiveQueryPublisher {
         }
     }
 }
+//p1 - seems that after backend methods relations are loaded for some reason - see trempim - intake doRequest backend method
+//p1 - reconsider the case in tremping where create user id was updated with some user and not the actual user
+//[ ] - when value changes for field with error, clear error - so the user will feel comfortable

package/esm/src/entity.d.ts

@@ -1,6 +1,6 @@
 import type { Allowed, AllowedForInstance } from './context';
 import type { FieldMetadata } from './column-interfaces';
-import type { EntityFilter, EntityIdFields, EntityMetadata, EntityOrderBy, EntityRef, FieldsMetadata, LifeCycleEvent } from './remult3/remult3';
+import type { EntityFilter, EntityIdFields, EntityMetadata, EntityOrderBy, EntityRef, FieldsMetadata, LifecycleEvent } from './remult3/remult3';
 export interface EntityOptions<entityType = any> {
     /**A human readable name for the entity */
     caption?: string;
@@ -55,20 +55,51 @@ export interface EntityOptions<entityType = any> {
      * this is the place to run logic that we want to run in any case before an entity is saved.
      * @example
      * @Entity<Task>("tasks", {
-     * saving: async task => {
-     *      task.lastUpdated = new Date()
-     *  }
-     *})
+     *   saving: async (task, e) => {
+     *     if (e.isNew) {
+     *       task.createdAt = new Date(); // Set the creation date for new tasks.
+     *     }
+     *     task.lastUpdated = new Date(); // Update the last updated date.
+     *   },
+     * })
+     * @param entity - The instance of the entity being saved.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
      */
-    saving?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** will be called after the Entity was saved to the data source. */
-    saved?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** Will be called before an Entity is deleted. */
-    deleting?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** Will be called after an Entity is deleted */
-    deleted?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** Will be called when the entity is being validated, usually prior to the `saving` event */
-    validation?: (row: entityType, ref: EntityRef<entityType>) => Promise<any> | any;
+    saving?: (entity: entityType, event: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs after an entity has been successfully saved.
+     *
+     * @param entity The instance of the entity that was saved.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    saved?: (entity: entityType, e: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs before an entity is deleted.
+     *
+     * @param entity The instance of the entity being deleted.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    deleting?: (entity: entityType, e: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs after an entity has been successfully deleted.
+     *
+     * @param entity The instance of the entity that was deleted.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    deleted?: (entity: entityType, e: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs to perform validation checks on an entity before saving.
+     * This hook is also executed on the frontend.
+     *
+     * @param entity The instance of the entity being validated.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    validation?: (entity: entityType, ref: LifecycleEvent<entityType>) => Promise<any> | any;
     /** The name of the table in the database that holds the data for this entity.
      * If no name is set, the `key` will be used instead.
      * @example
@@ -84,10 +115,10 @@ export interface EntityOptions<entityType = any> {
     /** An arrow function that identifies the `id` column to use for this entity
      * @example
      * //Single column id
-     * @Entity<Products>("products", { id:p=>p.productCode })
+     * @Entity<Products>("products", { id: {productCode: true} })
      * @example
      * //Multiple columns id
-     * @Entity<OrderDetails>("orderDetails", { id:od=> [od.orderId, od.productCode] })
+     * @Entity<OrderDetails>("orderDetails", { id:{ orderId:true, productCode:true} })
      */
     id?: EntityIdFields<entityType> | ((entity: FieldsMetadata<entityType>) => FieldMetadata | FieldMetadata[]);
     entityRefInit?: (ref: EntityRef<entityType>, row: entityType) => void;

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

@@ -190,7 +190,7 @@ export declare class columnDefsImpl implements FieldMetadata {
     constructor(settings: FieldOptions, entityDefs: EntityFullInfo<any>, remult: Remult);
     apiUpdateAllowed(item?: any): boolean;
     displayValue(item: any): string;
-    get includedInApi(): boolean;
+    includedInApi(item?: any): boolean;
     toInput(value: any, inputType?: string): string;
     fromInput(inputValue: string, inputType?: string): any;
     getDbName(): Promise<string>;

package/esm/src/remult3/RepositoryImplementation.js

@@ -1039,7 +1039,7 @@ class rowHelperBase {
         for (const col of this.columnsInfo) {
             if (!this.remult ||
                 col.includeInApi === undefined ||
-                this.remult.isAllowed(col.includeInApi)) {
+                this.remult.isAllowedForInstance(this.instance, col.includeInApi)) {
                 let val;
                 let lu = this.lookups.get(col.key);
                 let disable = false;
@@ -1073,7 +1073,7 @@ class rowHelperBase {
         for (const col of this.columnsInfo) {
             if (keys.includes(col.key))
                 if (col.includeInApi === undefined ||
-                    this.remult.isAllowed(col.includeInApi)) {
+                    this.remult.isAllowedForInstance(this.instance, col.includeInApi)) {
                     if (!this.remult ||
                         ignoreApiAllowed ||
                         col.allowApiUpdate === undefined ||
@@ -1363,8 +1363,10 @@ export class rowHelperImplementation extends rowHelperBase {
                 await col.__performValidation();
             }
         }
-        if (this.info.entityInfo.validation)
-            await this.info.entityInfo.validation(this.instance, this);
+        if (this.info.entityInfo.validation) {
+            let e = this.buildLifeCycleEvent(() => { });
+            await this.info.entityInfo.validation(this.instance, e);
+        }
         if (this.repository.listeners)
             for (const listener of this.repository.listeners.filter((x) => x.validating)) {
                 await listener.validating(this.instance);
@@ -1635,10 +1637,10 @@ export class columnDefsImpl {
             .getEntityMetadataWithoutBreakingTheEntity(item)
             .fields.find(this.key).displayValue;
     }
-    get includedInApi() {
+    includedInApi(item) {
         if (this.options.includeInApi === undefined)
             return true;
-        return this.remult.isAllowed(this.options.includeInApi); //TODO 2- consolidate other code paths to go through here
+        return this.remult.isAllowedForInstance(item, this.options.includeInApi);
     }
     toInput(value, inputType) {
         return this.valueConverter.toInput(value, inputType);

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

@@ -29,14 +29,48 @@ export interface EntityRef<entityType> extends Subscribable {
     readonly apiInsertAllowed: boolean;
     readonly isLoading: boolean;
 }
-export interface LifeCycleEvent<entityType> {
+/**
+ * Represents a lifecycle event associated with an entity instance. These events
+ * are triggered during various stages of the entity's lifecycle, such as validation,
+ * saving, saved, deleting, and deleted.
+ *
+ * @template entityType The type of the entity associated with the event.
+ * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+ */
+export interface LifecycleEvent<entityType> {
+    /**
+     * Indicates whether the entity is new or existing.
+     */
     isNew: boolean;
+    /**
+     * A reference to the fields of the entity, providing access to its properties.
+     */
     fields: FieldsRef<entityType>;
+    /**
+     * The ID of the entity.
+     */
     id: idType<entityType>;
+    /**
+     * The original ID of the entity, useful for tracking changes.
+     */
     originalId: idType<entityType>;
+    /**
+     * The repository associated with the entity, providing access to repository methods.
+     */
     repository: Repository<entityType>;
+    /**
+     * Metadata describing the entity's structure and configuration.
+     */
     metadata: EntityMetadata<entityType>;
+    /**
+     * A function that can be used to prevent the default behavior associated with
+     * the lifecycle event.
+     */
     preventDefault: VoidFunction;
+    /**
+     * A reference to the repository relations associated with the entity, providing
+     * access to related entities and their data.
+     */
     relations: RepositoryRelations<entityType>;
 }
 export interface ControllerRef<entityType> extends Subscribable {
@@ -461,6 +495,12 @@ export interface RelationInfo {
  * @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>> = {
+    /**
+     * An object specifying custom field names for the relation.
+     * Each key represents a field in the related entity, and its value is the corresponding field in the source entity.
+     * For example, `{ customerId: 'id' }` maps the 'customerId' field in the related entity to the 'id' field in the source entity.
+     * This is useful when you want to define custom field mappings for the relation.
+     */
     fields?: {
         [K in keyof toEntity]?: keyof fromEntity;
     };

package/esm/src/remult3/remult3.js

@@ -1,3 +1,31 @@
 export {};
 //p1 - include relations in the api docs
 //p1 - include Relation options in the api docs
+//p1 - fix { allowApiRead: r => r.user.name === 'superman' } } in allowed for instace docs
+//p1 - fix seeallowed in ref_entity
+//p1 - write doc about controlling updates of rows...
+//p1 - 'eventId' autocomplete in task app did not work
+//p1 - need a way to extract the fields from the relation - for generating relation based sql
+//p1 - remult object was used outside context
+// ```
+// sqlExpression: async (e) => {
+//   const v = await dbNamesOf(volunteerInTask)
+//   return `select true from ${v} where ${
+//     v.task
+//   }=${await e.getDbName()}.${await e.fields.id.getDbName()} and ${SqlDatabase.filterToRaw<volunteerInTask>(
+//     repo(volunteerInTask),
+//     {
+//       canceled: false,
+//     }
+//   )}`
+// },
+// })
+// ```
+//p2 - consider includeInApi as AllowedForInstance
+//p1 - why didn't this._.relations.statusChanges.insert({})work?
+//p1 - active record with include thinks that the row was change!
+//p1 - add docs for apply changes
+//p1 - update related field with null should respect it's allowed null - otherwise we get a null error for that field.
+//p1 - when the include doesn't find the many to one - it deletes the id!!!
+//y1 - discuss a default date formatter
+//p1 - consider using this in saving etc...

package/graphql.js

@@ -908,7 +908,7 @@ function translateWhereToRestBody(fields, _a) {
     var result = {};
     var _loop_3 = function (field) {
         var e_8, _c;
-        if (field.includedInApi === false)
+        if (field.options.includeInApi === false)
             return "continue";
         var condition = where[field.key];
         if (condition) {

package/index.d.ts

@@ -30,4 +30,16 @@ export { ValueConverters } from './src/valueConverters';
 export { remult } from './src/remult-proxy';
 export { SubscriptionServer, LiveQueryStorage, StoredQuery, InMemoryLiveQueryStorage, } from './src/live-query/SubscriptionServer';
 export { SubscriptionListener, SubscriptionClientConnection, SubscriptionClient, SubscriptionChannel, LiveQueryChange, Unsubscribe, } from './src/live-query/SubscriptionChannel';
+/**
+ * A convenient shortcut function to quickly obtain a repository for a specific entity type in Remult.
+ *
+ * @param entity The entity class type for which you want to get a repository.
+ * @returns A repository instance for the specified entity type.
+ *
+ * Example usage:
+ * ```ts
+ * await repo(Task).find()
+ * await repo(Customer).insert()
+ * ```
+ */
 export declare function repo<entityType>(entity: ClassType<entityType>): import("./src/remult3/remult3").Repository<entityType>;

package/index.js

@@ -67,6 +67,18 @@ var SubscriptionServer_1 = require("./src/live-query/SubscriptionServer");
 Object.defineProperty(exports, "InMemoryLiveQueryStorage", { enumerable: true, get: function () { return SubscriptionServer_1.InMemoryLiveQueryStorage; } });
 var SubscriptionChannel_1 = require("./src/live-query/SubscriptionChannel");
 Object.defineProperty(exports, "SubscriptionChannel", { enumerable: true, get: function () { return SubscriptionChannel_1.SubscriptionChannel; } });
+/**
+ * A convenient shortcut function to quickly obtain a repository for a specific entity type in Remult.
+ *
+ * @param entity The entity class type for which you want to get a repository.
+ * @returns A repository instance for the specified entity type.
+ *
+ * Example usage:
+ * ```ts
+ * await repo(Task).find()
+ * await repo(Customer).insert()
+ * ```
+ */
 function repo(entity) {
     return remult_proxy_2.remult.repo(entity);
 }

package/package.json

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

package/src/CompoundIdField.d.ts

@@ -6,7 +6,7 @@ export declare class CompoundIdField implements FieldMetadata<string> {
     constructor(...columns: FieldMetadata[]);
     apiUpdateAllowed(item: any): boolean;
     displayValue(item: any): string;
-    includedInApi: boolean;
+    includedInApi(item: any): boolean;
     toInput(value: string, inputType?: string): string;
     fromInput(inputValue: string, inputType?: string): string;
     getDbName(): Promise<string>;

package/src/CompoundIdField.js

@@ -15,6 +15,9 @@ var CompoundIdField = /** @class */ (function () {
     CompoundIdField.prototype.displayValue = function (item) {
         throw new Error('Method not implemented.');
     };
+    CompoundIdField.prototype.includedInApi = function (item) {
+        throw new Error('Method not implemented.');
+    };
     CompoundIdField.prototype.toInput = function (value, inputType) {
         throw new Error('Method not implemented.');
     };

package/src/column-interfaces.d.ts

@@ -1,6 +1,6 @@
 import type { ClassType } from '../classType';
-import type { Allowed, AllowedForInstance } from './context';
-import type { EntityMetadata, FieldRef, LifeCycleEvent, OmitEB } from './remult3/remult3';
+import type { AllowedForInstance } from './context';
+import type { EntityMetadata, FieldRef, LifecycleEvent, OmitEB } from './remult3/remult3';
 export interface FieldOptions<entityType = any, valueType = any> {
     /** A human readable name for the field. Can be used to achieve a consistent caption for a field throughout the app
      * @example
@@ -11,7 +11,7 @@ export interface FieldOptions<entityType = any, valueType = any> {
     allowNull?: boolean;
     /** If this field data is included in the api.
      * @see [allowed](http://remult.dev/docs/allowed.html)*/
-    includeInApi?: Allowed;
+    includeInApi?: AllowedForInstance<entityType>;
     /** If this field data can be updated in the api.
      * @see [allowed](http://remult.dev/docs/allowed.html)*/
     allowApiUpdate?: AllowedForInstance<entityType>;
@@ -37,7 +37,7 @@ export interface FieldOptions<entityType = any, valueType = any> {
      */
     validate?: ((entity: entityType, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>) | ((entity: entityType, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>)[];
     /** Will be fired before this field is saved to the server/database */
-    saving?: (entity: entityType, e: LifeCycleEvent<entityType>, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>;
+    saving?: (entity: entityType, e: LifecycleEvent<entityType>, fieldRef: FieldRef<entityType, valueType>) => any | Promise<any>;
     /**  An expression that will determine this fields value on the backend and be provided to the front end*/
     serverExpression?: (entity: entityType) => valueType | Promise<valueType>;
     /** The name of the column in the database that holds the data for this field. If no name is set, the key will be used instead.
@@ -134,7 +134,7 @@ export interface FieldMetadata<valueType = any, entityType = any> {
      */
     displayValue(item: Partial<OmitEB<entityType>>): string;
     apiUpdateAllowed(item?: Partial<OmitEB<entityType>>): boolean;
-    readonly includedInApi: boolean;
+    includedInApi(item?: Partial<OmitEB<entityType>>): boolean;
     /** Adapts the value for usage with html input
      * @example
      * @Fields.dateOnly()

package/src/context.js

@@ -450,3 +450,6 @@ var transactionLiveQueryPublisher = /** @class */ (function () {
     };
     return transactionLiveQueryPublisher;
 }());
+//p1 - seems that after backend methods relations are loaded for some reason - see trempim - intake doRequest backend method
+//p1 - reconsider the case in tremping where create user id was updated with some user and not the actual user
+//[ ] - when value changes for field with error, clear error - so the user will feel comfortable

package/src/entity.d.ts

@@ -1,6 +1,6 @@
 import type { Allowed, AllowedForInstance } from './context';
 import type { FieldMetadata } from './column-interfaces';
-import type { EntityFilter, EntityIdFields, EntityMetadata, EntityOrderBy, EntityRef, FieldsMetadata, LifeCycleEvent } from './remult3/remult3';
+import type { EntityFilter, EntityIdFields, EntityMetadata, EntityOrderBy, EntityRef, FieldsMetadata, LifecycleEvent } from './remult3/remult3';
 export interface EntityOptions<entityType = any> {
     /**A human readable name for the entity */
     caption?: string;
@@ -55,20 +55,51 @@ export interface EntityOptions<entityType = any> {
      * this is the place to run logic that we want to run in any case before an entity is saved.
      * @example
      * @Entity<Task>("tasks", {
-     * saving: async task => {
-     *      task.lastUpdated = new Date()
-     *  }
-     *})
+     *   saving: async (task, e) => {
+     *     if (e.isNew) {
+     *       task.createdAt = new Date(); // Set the creation date for new tasks.
+     *     }
+     *     task.lastUpdated = new Date(); // Update the last updated date.
+     *   },
+     * })
+     * @param entity - The instance of the entity being saved.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
      */
-    saving?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** will be called after the Entity was saved to the data source. */
-    saved?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** Will be called before an Entity is deleted. */
-    deleting?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** Will be called after an Entity is deleted */
-    deleted?: (row: entityType, e: LifeCycleEvent<entityType>) => Promise<any> | any;
-    /** Will be called when the entity is being validated, usually prior to the `saving` event */
-    validation?: (row: entityType, ref: EntityRef<entityType>) => Promise<any> | any;
+    saving?: (entity: entityType, event: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs after an entity has been successfully saved.
+     *
+     * @param entity The instance of the entity that was saved.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    saved?: (entity: entityType, e: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs before an entity is deleted.
+     *
+     * @param entity The instance of the entity being deleted.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    deleting?: (entity: entityType, e: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs after an entity has been successfully deleted.
+     *
+     * @param entity The instance of the entity that was deleted.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    deleted?: (entity: entityType, e: LifecycleEvent<entityType>) => Promise<any> | any;
+    /**
+     * A hook that runs to perform validation checks on an entity before saving.
+     * This hook is also executed on the frontend.
+     *
+     * @param entity The instance of the entity being validated.
+     * @param event - an @link LifeCycleEvent object
+     * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+     */
+    validation?: (entity: entityType, ref: LifecycleEvent<entityType>) => Promise<any> | any;
     /** The name of the table in the database that holds the data for this entity.
      * If no name is set, the `key` will be used instead.
      * @example
@@ -84,10 +115,10 @@ export interface EntityOptions<entityType = any> {
     /** An arrow function that identifies the `id` column to use for this entity
      * @example
      * //Single column id
-     * @Entity<Products>("products", { id:p=>p.productCode })
+     * @Entity<Products>("products", { id: {productCode: true} })
      * @example
      * //Multiple columns id
-     * @Entity<OrderDetails>("orderDetails", { id:od=> [od.orderId, od.productCode] })
+     * @Entity<OrderDetails>("orderDetails", { id:{ orderId:true, productCode:true} })
      */
     id?: EntityIdFields<entityType> | ((entity: FieldsMetadata<entityType>) => FieldMetadata | FieldMetadata[]);
     entityRefInit?: (ref: EntityRef<entityType>, row: entityType) => void;

package/src/remult3/RepositoryImplementation.d.ts

@@ -190,7 +190,7 @@ export declare class columnDefsImpl implements FieldMetadata {
     constructor(settings: FieldOptions, entityDefs: EntityFullInfo<any>, remult: Remult);
     apiUpdateAllowed(item?: any): boolean;
     displayValue(item: any): string;
-    get includedInApi(): boolean;
+    includedInApi(item?: any): boolean;
     toInput(value: any, inputType?: string): string;
     fromInput(inputValue: string, inputType?: string): any;
     getDbName(): Promise<string>;

package/src/remult3/RepositoryImplementation.js

@@ -1635,7 +1635,7 @@ var rowHelperBase = /** @class */ (function () {
                 var col = _c.value;
                 if (!this.remult ||
                     col.includeInApi === undefined ||
-                    this.remult.isAllowed(col.includeInApi)) {
+                    this.remult.isAllowedForInstance(this.instance, col.includeInApi)) {
                     var val = void 0;
                     var lu = this.lookups.get(col.key);
                     var disable = false;
@@ -1686,7 +1686,7 @@ var rowHelperBase = /** @class */ (function () {
                                 col = _b.value;
                                 if (keys.includes(col.key))
                                     if (col.includeInApi === undefined ||
-                                        this.remult.isAllowed(col.includeInApi)) {
+                                        this.remult.isAllowedForInstance(this.instance, col.includeInApi)) {
                                         if (!this.remult ||
                                             ignoreApiAllowed ||
                                             col.allowApiUpdate === undefined ||
@@ -2264,7 +2264,7 @@ var rowHelperImplementation = /** @class */ (function (_super) {
     };
     rowHelperImplementation.prototype.__performColumnAndEntityValidations = function () {
         return tslib_1.__awaiter(this, void 0, void 0, function () {
-            var _a, _b, c, col, e_37_1, _c, _d, listener, e_38_1;
+            var _a, _b, c, col, e_37_1, e, _c, _d, listener, e_38_1;
             var e_37, _e, e_38, _f;
             return tslib_1.__generator(this, function (_g) {
                 switch (_g.label) {
@@ -2297,7 +2297,8 @@ var rowHelperImplementation = /** @class */ (function (_super) {
                         return [7 /*endfinally*/];
                     case 7:
                         if (!this.info.entityInfo.validation) return [3 /*break*/, 9];
-                        return [4 /*yield*/, this.info.entityInfo.validation(this.instance, this)];
+                        e = this.buildLifeCycleEvent(function () { });
+                        return [4 /*yield*/, this.info.entityInfo.validation(this.instance, e)];
                     case 8:
                         _g.sent();
                         _g.label = 9;
@@ -2725,15 +2726,11 @@ var columnDefsImpl = /** @class */ (function () {
             .getEntityMetadataWithoutBreakingTheEntity(item)
             .fields.find(this.key).displayValue;
     };
-    Object.defineProperty(columnDefsImpl.prototype, "includedInApi", {
-        get: function () {
-            if (this.options.includeInApi === undefined)
-                return true;
-            return this.remult.isAllowed(this.options.includeInApi); //TODO 2- consolidate other code paths to go through here
-        },
-        enumerable: false,
-        configurable: true
-    });
+    columnDefsImpl.prototype.includedInApi = function (item) {
+        if (this.options.includeInApi === undefined)
+            return true;
+        return this.remult.isAllowedForInstance(item, this.options.includeInApi);
+    };
     columnDefsImpl.prototype.toInput = function (value, inputType) {
         return this.valueConverter.toInput(value, inputType);
     };

package/src/remult3/remult3.d.ts

@@ -29,14 +29,48 @@ export interface EntityRef<entityType> extends Subscribable {
     readonly apiInsertAllowed: boolean;
     readonly isLoading: boolean;
 }
-export interface LifeCycleEvent<entityType> {
+/**
+ * Represents a lifecycle event associated with an entity instance. These events
+ * are triggered during various stages of the entity's lifecycle, such as validation,
+ * saving, saved, deleting, and deleted.
+ *
+ * @template entityType The type of the entity associated with the event.
+ * @see [Entity Lifecycle Hooks](http://remult.dev/docs/lifecycle-hooks)
+ */
+export interface LifecycleEvent<entityType> {
+    /**
+     * Indicates whether the entity is new or existing.
+     */
     isNew: boolean;
+    /**
+     * A reference to the fields of the entity, providing access to its properties.
+     */
     fields: FieldsRef<entityType>;
+    /**
+     * The ID of the entity.
+     */
     id: idType<entityType>;
+    /**
+     * The original ID of the entity, useful for tracking changes.
+     */
     originalId: idType<entityType>;
+    /**
+     * The repository associated with the entity, providing access to repository methods.
+     */
     repository: Repository<entityType>;
+    /**
+     * Metadata describing the entity's structure and configuration.
+     */
     metadata: EntityMetadata<entityType>;
+    /**
+     * A function that can be used to prevent the default behavior associated with
+     * the lifecycle event.
+     */
     preventDefault: VoidFunction;
+    /**
+     * A reference to the repository relations associated with the entity, providing
+     * access to related entities and their data.
+     */
     relations: RepositoryRelations<entityType>;
 }
 export interface ControllerRef<entityType> extends Subscribable {
@@ -461,6 +495,12 @@ export interface RelationInfo {
  * @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>> = {
+    /**
+     * An object specifying custom field names for the relation.
+     * Each key represents a field in the related entity, and its value is the corresponding field in the source entity.
+     * For example, `{ customerId: 'id' }` maps the 'customerId' field in the related entity to the 'id' field in the source entity.
+     * This is useful when you want to define custom field mappings for the relation.
+     */
     fields?: {
         [K in keyof toEntity]?: keyof fromEntity;
     };

package/src/remult3/remult3.js

@@ -2,3 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 //p1 - include relations in the api docs
 //p1 - include Relation options in the api docs
+//p1 - fix { allowApiRead: r => r.user.name === 'superman' } } in allowed for instace docs
+//p1 - fix seeallowed in ref_entity
+//p1 - write doc about controlling updates of rows...
+//p1 - 'eventId' autocomplete in task app did not work
+//p1 - need a way to extract the fields from the relation - for generating relation based sql
+//p1 - remult object was used outside context
+// ```
+// sqlExpression: async (e) => {
+//   const v = await dbNamesOf(volunteerInTask)
+//   return `select true from ${v} where ${
+//     v.task
+//   }=${await e.getDbName()}.${await e.fields.id.getDbName()} and ${SqlDatabase.filterToRaw<volunteerInTask>(
+//     repo(volunteerInTask),
+//     {
+//       canceled: false,
+//     }
+//   )}`
+// },
+// })
+// ```
+//p2 - consider includeInApi as AllowedForInstance
+//p1 - why didn't this._.relations.statusChanges.insert({})work?
+//p1 - active record with include thinks that the row was change!
+//p1 - add docs for apply changes
+//p1 - update related field with null should respect it's allowed null - otherwise we get a null error for that field.
+//p1 - when the include doesn't find the many to one - it deletes the id!!!
+//y1 - discuss a default date formatter
+//p1 - consider using this in saving etc...