Breeze

Appearance

breeze-client / EntityAspect

Class: EntityAspect ​

Defined in: src/entity/entity-aspect.ts:112

An EntityAspect instance is associated with every attached entity and is accessed via the entity's 'entityAspect' property.

The EntityAspect itself provides properties to determine and modify the EntityState of the entity and has methods that provide a variety of services including validation and change tracking.

An EntityAspect will almost never need to be constructed directly. You will usually get an EntityAspect by accessing an entities 'entityAspect' property. This property will be automatically attached when an entity is created via either a query, import or EntityManager.createEntity call.

ts
// assume order is an order entity attached to an EntityManager.
var aspect = order.entityAspect;
var currentState = aspect.entityState;

Extended by ​

Properties ​

entity? ​

optional entity?: Entity

Defined in: src/entity/entity-aspect.ts:114

The Entity that this aspect is associated with. Read Only

entityManager? ​

optional entityManager?: EntityManager

Defined in: src/entity/entity-aspect.ts:116

The EntityManager that contains this entity. Read Only

extraMetadata? ​

optional extraMetadata?: any

Defined in: src/entity/entity-aspect.ts:154

Extra metadata about this entity such as the entity's etag. You may extend this object with your own metadata information. Breeze (de)serializes this object when importing/exporting the entity.

hasTempKey? ​

optional hasTempKey?: boolean

Defined in: src/entity/entity-aspect.ts:148

Whether this entity has a temporary EntityKey.

hasValidationErrors ​

hasValidationErrors: boolean

Defined in: src/entity/entity-aspect.ts:146

Whether this entity has any validation errors. Read Only

isBeingSaved ​

isBeingSaved: boolean

Defined in: src/entity/entity-aspect.ts:141

Whether this entity is in the process of being saved. Read Only

originalValues ​

originalValues: Record<string, any>

Defined in: src/entity/entity-aspect.ts:144

The 'original values' of this entity where they are different from the 'current values'. This is a map where the key is a property name and the value is the 'original value' of the property.

propertyChanged ​

propertyChanged: BreezeEvent<PropertyChangedEventArgs>

Defined in: src/entity/entity-aspect.ts:203

A BreezeEvent that fires whenever a value of one of this entity's properties change.

Event Args ​

    • entity - The entity whose property has changed.
    • property - The DataProperty that changed.
    • propertyName - The name of the property that changed. This value will be 'null' for operations that replace the entire entity. This includes queries, imports and saves that require a merge. The remaining parameters will not exist in this case either. This will actually be a "property path" for any properties of a complex type.
    • oldValue - The old value of this property before the change.
    • newValue - The new value of this property after the change.
    • parent - The immediate parent object for the changed property. This will be a ComplexType instance as opposed to an Entity for any complex type or nested complex type properties.
ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.propertyChanged.subscribe(
function (propertyChangedArgs) {
    // this code will be executed anytime a property value changes on the 'order' entity.
    var entity = propertyChangedArgs.entity; // Note: entity === order
    var propertyNameChanged = propertyChangedArgs.propertyName;
    var oldValue = propertyChangedArgs.oldValue;
    var newValue = propertyChangedArgs.newValue;
});

Event ​

setDeleted ​

setDeleted: () => any

Defined in: src/entity/entity-aspect.ts:448

Sets the entity to an EntityState of 'Deleted'. This both marks the entity as being scheduled for deletion during the next 'Save' call but also removes the entity from all of its related entities. If the current entityState is 'Added', then setDeleted() will mark it 'Detached' The same operation can be performed by calling EntityAspect.setEntityState.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.setDeleted();
// The 'order' entity will now be in a 'Deleted' state and it will no longer have any 'related' entities.

Returns ​

any

setDetached ​

setDetached: () => any

Defined in: src/entity/entity-aspect.ts:461

Sets the entity to an EntityState of 'Detached'. This removes the entity from all of its related entities, but does NOT change the EntityState of any existing entities. The same operation can be performed by calling EntityAspect.setEntityState.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.setDetached();
// The 'order' entity will now be in a 'Detached' state and it will no longer have any 'related' entities.

Returns ​

any

setModified ​

setModified: () => any

Defined in: src/entity/entity-aspect.ts:434

Sets the entity to an EntityState of 'Modified'. This can also be achieved by changing the value of any property on an 'Unchanged' entity. The same operation can be performed by calling EntityAspect.setEntityState.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.setModified();
// The 'order' entity will now be in a 'Modified' state.

Returns ​

any

setUnchanged ​

setUnchanged: () => any

Defined in: src/entity/entity-aspect.ts:420

Sets the entity to an EntityState of 'Unchanged'. This is also the equivalent of calling EntityAspect.acceptChanges. The same operation can be performed by calling EntityAspect.setEntityState.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.setUnchanged();
// The 'order' entity will now be in an 'Unchanged' state with any changes committed.

Returns ​

any

validationErrorsChanged ​

validationErrorsChanged: BreezeEvent<ValidationErrorsChangedEventArgs>

Defined in: src/entity/entity-aspect.ts:176

A BreezeEvent that fires whenever any of the validation errors on this entity change. Note that this might be the removal of an error when some data on the entity is fixed.

Event Args ​

    • entity - The entity on which the validation errors are being added or removed.
    • added - An array containing any newly added ValidationErrors
    • removed - An array containing any newly removed ValidationErrors. This is those errors that have been 'fixed'.
ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.validationErrorsChanged.subscribe(
function (validationChangeArgs) {
  // this code will be executed anytime a property value changes on the 'order' entity.
  var entity == validationChangeArgs.entity; // Note: entity === order
  var errorsAdded = validationChangeArgs.added;
  var errorsCleared = validationChangeArgs.removed;
});

Event ​

wasLoaded? ​

optional wasLoaded?: boolean

Defined in: src/entity/entity-aspect.ts:150

Whether this entity was created by being loaded from the database

Accessors ​

entityState ​

Get Signature ​

get entityState(): EntityState

Defined in: src/entity/entity-aspect.ts:127

The EntityState of this entity. Read Only

Returns ​

EntityState

Set Signature ​

set entityState(entityState): void

Defined in: src/entity/entity-aspect.ts:130

Parameters ​
entityState ​

EntityState

Returns ​

void

isValidating ​

Get Signature ​

get isValidating(): boolean

Defined in: src/entity/entity-aspect.ts:218

Whether an async validator is still running for this entity - see EntityAspect.validateEntityAsync. Read Only

Returns ​

boolean

Methods ​

acceptChanges() ​

acceptChanges(): void

Defined in: src/entity/entity-aspect.ts:345

Returns the entity to an EntityState of 'Unchanged' by committing all changes made since the entity was last queried had 'acceptChanges' called on it.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.acceptChanges();
// The 'order' entity will now be in an 'Unchanged' state with any changes committed.

Returns ​

void

addValidationError() ​

addValidationError(validationError): void

Defined in: src/entity/entity-aspect.ts:821

Adds a validation error.

An error added here stops the entity being saved - validateEntity returns false and saveChanges rejects - until it is removed with EntityAspect.removeValidationError or EntityAspect.clearValidationErrors. Editing the property does not remove it: Breeze cannot re-check a rule it did not run. Give the error a key, and a failed save names it by that key in errorName.

Parameters ​

validationError ​

ValidationError

Returns ​

void

clearValidationErrors() ​

clearValidationErrors(): void

Defined in: src/entity/entity-aspect.ts:857

Removes all of the validation errors for a specified entity

Returns ​

void

getChangedProperties() ​

getChangedProperties(): string[]

Defined in: src/entity/entity-aspect.ts:808

The data properties whose value now differs from the one the entity was last saved or accepted with - as paths, such as 'location.city', for those of a complex property, and by name for an array property whose contents changed. A property edited and then set back is not included, although it stays in EntityAspect.originalValues. Dates are compared by time.

ts
order.freight = 99;
order.shipCity = order.shipCity;              // set, but to the same value
order.entityAspect.getChangedProperties();    // ['freight']

Always empty for an Added entity, which has no original values to differ from.

Returns ​

string[]

getKey() ​

getKey(forceRefresh?): EntityKey

Defined in: src/entity/entity-aspect.ts:319

Returns the EntityKey for this Entity.

ts
// assume order is an order entity attached to an EntityManager.
var entityKey = order.entityAspect.getKey();

Parameters ​

forceRefresh? ​

boolean = false

(boolean=false) Forces the recalculation of the key. This should normally be unnecessary.

Returns ​

EntityKey

The EntityKey associated with this Entity.

getOriginalValue() ​

getOriginalValue(propertyName): any

Defined in: src/entity/entity-aspect.ts:784

The value a property had before the entity's pending changes: its original value if it has been edited since the entity was last saved or accepted, and its current value if not. So it answers "what was this?" without first asking whether it changed.

ts
order.freight = 99;
order.entityAspect.getOriginalValue('freight');    // the freight before the edit
order.entityAspect.getOriginalValue('shipCity');   // unchanged, so its current value

Also takes a path into a complex property, such as 'location.city'.

Parameters ​

propertyName ​

string

A data property of this entity, or a path to one in a complex property.

Returns ​

any

getParentKey() ​

getParentKey(navigationProperty): EntityKey | null

Defined in: src/entity/entity-aspect.ts:877

Returns an EntityKey for the entity pointed to by the specified scalar NavigationProperty. This only returns an EntityKey if the current entity is a 'child' entity along the specified NavigationProperty. i.e. has a single parent.

Parameters ​

NavigationProperty

The NavigationProperty ( pointing to a parent).

Returns ​

EntityKey | null

Either a parent EntityKey if this is a 'child' entity or null;

getPropertyValue() ​

getPropertyValue(property): any

Defined in: src/entity/entity-aspect.ts:892

Returns the value of a specified DataProperty or NavigationProperty or 'property path'.

Parameters ​

property ​

string | DataProperty | NavigationProperty

Returns ​

any

getValidationErrors() ​

Returns the validation errors associated with either the entire entity or any specified property.

This method can return all of the errors for an Entity

ts
// assume order is an order entity attached to an EntityManager.
var valErrors = order.entityAspect.getValidationErrors();

as well as those for just a specific property.

ts
// assume order is an order entity attached to an EntityManager.
var orderDateErrors = order.entityAspect.getValidationErrors("OrderDate");

which can also be expressed as

ts
// assume order is an order entity attached to an EntityManager.
var orderDateProperty = order.entityType.getProperty("OrderDate");
var orderDateErrors = order.entityAspect.getValidationErrors(orderDateProperty);

Param ​

property

The property for which validation errors should be retrieved. If omitted, all of the validation errors for this entity will be returned.

Call Signature ​

getValidationErrors(): ValidationError[]

Defined in: src/entity/entity-aspect.ts:728

Returns ​

ValidationError[]

Call Signature ​

getValidationErrors(property): ValidationError[]

Defined in: src/entity/entity-aspect.ts:729

Parameters ​
property ​

string

Returns ​

ValidationError[]

Call Signature ​

getValidationErrors(property): ValidationError[]

Defined in: src/entity/entity-aspect.ts:730

Parameters ​
property ​

EntityProperty

Returns ​

ValidationError[]

isNavigationPropertyLoaded() ​

Determines whether a navigationProperty on this entity has already been loaded.

A navigation property is considered loaded when any of the following three conditions applies:

  1. It was fetched from the backend server.
    This can be the result of an expand query or a call to the EntityAspect.loadNavigationProperty method.
    Note that even if the fetch returns nothing the property is still marked as loaded in this case.
  2. The property is scalar and has been set to a nonnull value.
  3. The EntityAspect.markNavigationPropertyAsLoaded was called.
ts
var wasLoaded = emp.entityAspect.isNavigationPropertyLoaded("Orders");

Param ​

navigationProperty

The NavigationProperty or name of NavigationProperty to 'load'.

Call Signature ​

isNavigationPropertyLoaded(navigationProperty): boolean

Defined in: src/entity/entity-aspect.ts:577

Parameters ​

string

Returns ​

boolean

Call Signature ​

isNavigationPropertyLoaded(navigationProperty): boolean

Defined in: src/entity/entity-aspect.ts:578

Parameters ​

NavigationProperty

Returns ​

boolean

loadNavigationProperty() ​

Performs a query for the value of a specified NavigationProperty. Async

ts
emp.entityAspect.loadNavigationProperty("Orders").then(function (data) {
    var orders = data.results;
}).catch(function (exception) {
    // handle exception here;
});

Param ​

navigationProperty

The NavigationProperty or the name of the NavigationProperty to 'load'.

Param ​

callback

Deprecated. Function to call on success.

Param ​

errorCallback

Deprecated. Function to call on failure.

Call Signature ​

loadNavigationProperty(navigationProperty): Promise<QueryResult<any>>

Defined in: src/entity/entity-aspect.ts:523

Parameters ​

string

Returns ​

Promise<QueryResult<any>>

Call Signature ​

loadNavigationProperty(navigationProperty): Promise<QueryResult<any>>

Defined in: src/entity/entity-aspect.ts:524

Parameters ​

NavigationProperty

Returns ​

Promise<QueryResult<any>>

Call Signature ​

loadNavigationProperty(navigationProperty, callback?, errorCallback?): Promise<QueryResult<any>>

Defined in: src/entity/entity-aspect.ts:526

Parameters ​

string

callback? ​

QuerySuccessCallback

errorCallback? ​

QueryErrorCallback

Returns ​

Promise<QueryResult<any>>

Deprecated ​

Await the returned promise instead of passing callbacks.

Call Signature ​

loadNavigationProperty(navigationProperty, callback?, errorCallback?): Promise<QueryResult<any>>

Defined in: src/entity/entity-aspect.ts:528

Parameters ​

NavigationProperty

callback? ​

QuerySuccessCallback

errorCallback? ​

QueryErrorCallback

Returns ​

Promise<QueryResult<any>>

Deprecated ​

Await the returned promise instead of passing callbacks.

markNavigationPropertyAsLoaded() ​

markNavigationPropertyAsLoaded(navigationProperty): void

Defined in: src/entity/entity-aspect.ts:571

Marks this navigationProperty on this entity as already having been loaded.

ts
emp.entityAspect.markNavigationPropertyAsLoaded("Orders");

Parameters ​

string | NavigationProperty

The NavigationProperty or name of NavigationProperty to 'load'.

Returns ​

void

rejectChanges() ​

rejectChanges(): void

Defined in: src/entity/entity-aspect.ts:366

Returns the entity to an EntityState of 'Unchanged' by rejecting all changes made to it since the entity was last queried had 'rejectChanges' called on it.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.rejectChanges();
// The 'order' entity will now be in an 'Unchanged' state with any changes rejected.

Returns ​

void

removeValidationError() ​

Removes a validation error.

Param ​

validationErrorOrKey

A ValidationError, a ValidationError 'key' value, or a Validator - in which case every error that validator produced on this entity is removed.

Call Signature ​

removeValidationError(validationError): void

Defined in: src/entity/entity-aspect.ts:828

Parameters ​
validationError ​

ValidationError

Returns ​

void

Call Signature ​

removeValidationError(validationKey): void

Defined in: src/entity/entity-aspect.ts:829

Parameters ​
validationKey ​

string

Returns ​

void

Call Signature ​

removeValidationError(validator): void

Defined in: src/entity/entity-aspect.ts:830

Parameters ​
validator ​

Validator

Returns ​

void

setAdded() ​

setAdded(): boolean

Defined in: src/entity/entity-aspect.ts:407

Sets the entity to an EntityState of 'Added'. This is NOT the equivalent of calling EntityManager.addEntity because no key generation will occur for autogenerated keys as a result of this operation. As a result this operation can be problematic unless you are certain that the entity being marked 'Added' does not already exist in the database and does not have an autogenerated key. The same operation can be performed by calling EntityAspect.setEntityState.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.setAdded();
// The 'order' entity will now be in an 'Added' state.

Returns ​

boolean

setEntityState() ​

setEntityState(entityState): boolean

Defined in: src/entity/entity-aspect.ts:473

Sets the entity to the specified EntityState. See also 'setUnchanged', 'setModified', 'setDetached', etc.

ts
// assume order is an order entity attached to an EntityManager.
order.entityAspect.setEntityState(EntityState.Unchanged);
// The 'order' entity will now be in a 'Unchanged' state.

Parameters ​

entityState ​

EntityState

Returns ​

boolean

validateEntity() ​

validateEntity(): boolean

Defined in: src/entity/entity-aspect.ts:632

Performs validation on the entity, any errors encountered during the validation are available via the EntityAspect.getValidationErrors method. Validating an entity means executing all of the validators on both the entity itself as well as those on each of its properties.

ts
// assume order is an order entity attached to an EntityManager.
var isOk = order.entityAspect.validateEntity();
// isOk will be 'true' if there are no errors on the entity.
if (!isOk) {
    var errors = order.entityAspect.getValidationErrors();
}

Returns ​

boolean

Whether the entity can be saved: every validator passes, and no error added with EntityAspect.addValidationError remains. Errors from the server are not counted - a save clears them before validating, and the server checks again. This is the check saveChanges makes, so the two always agree.

validateEntityAsync() ​

validateEntityAsync(): Promise<boolean>

Defined in: src/entity/entity-aspect.ts:705

Validates the entity as EntityAspect.validateEntity does, and also runs its async validators - see Validator.isAsync - resolving when they have all answered. This is the check saveChanges makes when any of the entities it saves has an async validator.

ts
if (!await order.entityAspect.validateEntityAsync()) {
  const errors = order.entityAspect.getValidationErrors();
}

While it runs, EntityAspect.isValidating is true. If a property changes while one of its checks runs, the check is run again on the new value.

Returns ​

Promise<boolean>

Whether the entity can be saved, as EntityAspect.validateEntity answers, once the async validators' answers are in.

validateProperty() ​

Performs validation on a specific property of this entity, any errors encountered during the validation are available via the EntityAspect.getValidationErrors method. Validating a property means executing all of the validators on the specified property. This call is also made automatically anytime a property of an entity is changed.

ts
// assume order is an order entity attached to an EntityManager.
var isOk = order.entityAspect.validateProperty("Order");

or

ts
var orderDateProperty = order.entityType.getProperty("OrderDate");
var isOk = order.entityAspect.validateProperty(OrderDateProperty);

Param ​

property

The DataProperty or NavigationProperty to validate or a string with the name of the property or a property path with the path to a property of a complex object.

Param ​

context

A context object used to pass additional information to each Validator.

Call Signature ​

validateProperty(property, context?): boolean

Defined in: src/entity/entity-aspect.ts:646

Parameters ​
property ​

string

context? ​

any

Returns ​

boolean

Call Signature ​

validateProperty(property, context?): boolean

Defined in: src/entity/entity-aspect.ts:647

Parameters ​
property ​

DataProperty

context? ​

any

Returns ​

boolean

Call Signature ​

validateProperty(property, context?): boolean

Defined in: src/entity/entity-aspect.ts:648

Parameters ​
property ​

NavigationProperty

context? ​

any

Returns ​

boolean

validatePropertyAsync() ​

validatePropertyAsync(property, context?): Promise<boolean>

Defined in: src/entity/entity-aspect.ts:722

Validates one property as EntityAspect.validateProperty does, and also runs its async validators, resolving when they have all answered.

ts
const isOk = await customer.entityAspect.validatePropertyAsync("companyName");

Parameters ​

property ​

string | EntityProperty

The property, by DataProperty, NavigationProperty, name, or path to a property of a complex object.

context? ​

any

Additional context for each Validator.

Returns ​

Promise<boolean>

Whether the property can be saved, once the async validators' answers are in.

getPropertyPathValue() ​

static getPropertyPathValue(obj, propertyPath): any

Defined in: src/entity/entity-aspect.ts:292

Returns the value of a specified 'property path' for a specified entity.

The propertyPath can be either a string delimited with '.' or a string array.

Parameters ​

obj ​

Entity

propertyPath ​

string | string[]

Returns ​

any

Released under the MIT License.

Copyright © IdeaBlade