    import Property from 'f.lux/src/Property.js'

public class | source

# Property

#### Direct Subclass:

ArrayProperty, CollectionProperty, IndexedProperty, IsolatedProperty, MapProperty, ObjectProperty, PrimitiveProperty

#### Indirect Subclass:

LifecycleProperty, ModelProperty, PojoEndpointProperty, RestEndpointProperty, TransientProperty, TransientsProperty

Base class for custom f.lux properties. A `Property` has a lifespan from when the state property is mapped until it is replaced/deleted. This differs from Shadow as its lifespan that lasts from the time of mapping until the state property is replaced/deleted OR the shadow property is invalidated due to a local change or a descendant property change.

Most shadow state properties can be implemented without writing a `Property` subclass, relying on autoshadowing, or defining the state structure using StateType along with one of the built-in property class `createClass()` static methods. The primary reason for writing a `Property` subclass is to tie into the f.lux property life-cycle.

This class provides an experimental check pointing api. Check pointing allows the state to be recorded at a point in time and then later reset to that point. This is handy when a form may accept changes and then allow the user to cancel the edit session.

Life cycle methods:

- `propertyWillShadow()` - invoked just before a state property is going to be shadowed using this instance. Shadow state is not valid during this method.
- `propertyDidShadow()` - property was shadowed and fully functional.
- `propertyChildInvalidated(childProperty, sourceProperty)` - a child property mutation action has occurred and it's value will change in store's next update.
- `propertyDidUpdate()` - state managed by this property has changed.
- `propertyWillUnshadow()` - invoked just before the shadow property is removed from the shadow state because the state property being shadowed has been removed from the application state.

#### See:

- ArrayProperty
- CollectionProperty
- IndexedProperty
- MapProperty
- ObjectProperty

## Constructor Summary

Public Constructor
public | constructor(stateType: StateType) If a StateType is not passed to this constructor then one is located using StateType.from thus ensuring the f.lux shadowing process is defined for this property. |

## Member Summary

Public Members
public | [_ImplementationClass]: * |
public | [_ShadowClass]: * |
public | [_autoShadow]: * |
public | [_checkpoint]: {"data": *} |
public | [_impl]: * |
public | [_initialState]: * |
public | [_mixins]: *[] |
public | [_parent]: * |
public | [_pid]: * |
public | [_readonly]: * |
public | [_shader]: * |
public | [_stateType]: * |
public | [_store]: * |

## Method Summary

Public Methods
public | $$(): Property Use this.$$() in shadow methods to get access to the property. |
public | autoShadow(): boolean Gets if autoshadowing is enabled for this property. |
public | checkpoint() Copies the current actual state for later reset using Property#resetToCheckpoint. |
public | clearCheckpoint() Clears an existing checkpoint created using Property#checkpoint. |
public | create$(impl: *): Access Creates the object to be assigned to the shadow.$ property. |
public | dotPath(): string Gets the path from root property using a dot (`.`) separator. |
public | getCheckpoint(): * Gets the checkpoint state previously recorded using Property#checkpoint. |
public | getInitialState(state: *): * Gets the initial state for a property at the beginning of the property mounting process. |
public | hasCheckpoint(): boolean Gets if an existing checkpoint has be created using Property#checkpoint. |
public | initialState(): * Gets the result from StateType#computeInitialState. |
public | isActive(): boolean Gets if the property is currently shadowing an actual state property. |
public | isIsolated(): boolean Gets if property is an actual isolated property managed by the store. |
public | isReadonly(): boolean Gets if the property allows for assignment through the shadow state, ie `todo.desc = "go skiing"`. |
public | isRoot(): boolean Gets if this is the shadow state root property. |
public | name(): string | number The property name by which this property is referenced by the Property.parent. |
public | nextState(): * Gets what the actual state for this property will be after the Store updates all pending actions. |
public | owner(): Property Gets the object containing or managing this property. |
public | parent(): Property Gets the parent property. |
public | parentShadow(): Shadow Gets the parent's shadow property. |
public | path(): [] Gets the Property#name components from the root property to this property. |
public | pid(): number Gets the unique f.lux ID for this property. |
public | propertyChildInvalidated(childProperty: Property, sourceProperty: Property) A child property or one of its descendents wil be changing state. |
public | propertyDidShadow() Invoked by the f.lux shadowing process after a property initially shadows a state property. |
public | propertyDidUpdate() Invoked by the f.lux shadowing process after a property is reshadowed. |
public | propertyWillShadow() Invoked by the f.lux shadowing process just before a property initially shadows a state property. |
public | propertyWillUnshadow() Invoked by the f.lux shadowing process just before a property will be removed from the shadow state. |
public | resetToCheckpoint() Replaces the current property state with a checkpoint state previously recorded using Property#checkpoint. |
public | root(): Property Gets the shadow state root property for the Store managing this property. |
public | rootShadow(): Shadow Gets the root shadow state for the Store managing this property. |
public | setAutoshadow(auto: boolean): * Sets the auto shadow property flag. |
public | setImplementationClass(ImplClass: *) |
public | setInitialState(state: *): Property Explicitly sets an initial state that will be used if the state tree does not have a value for this property. |
public | setReadonly(readonly: *) Sets the readonly flag which will prevent an assignment from changing the value. |
public | setShadowClass(ShadowClass: Shadow) Sets the class to be used for the shadow api |
public | shader(state: *): * Gets the Shader instance for this property. |
public | shadowClass(): * Returns the Shadow subclass used to virtualize the state property. |
public | slashPath(): string Gets the path from root property using a slash (`/`) separator. |
public | state(): * Gets the actual state being shadowed. |
public | stateType(): * Gets the StateType used for creating this property. |
public | store(): * Gets the {@Link Store} containing the application state. |
public | touch() Triggers a reshadow of the properties shadow state. |
public | typeName(): * Gets this property's StateType.typeName value. |
public | update(callback: function) Makes changes to the next proeprty state. |

## Public Constructors

### public constructor(stateType: StateType) source

If a StateType is not passed to this constructor then one is located using StateType.from thus ensuring the f.lux shadowing process is defined for this property.

#### Params:

Name | Type | Attribute | Description
stateType | StateType | optional | a specialized StateType instance describing how f.lux should shadow this property.

## Public Members

### public [_ImplementationClass]: * source

### public [_ShadowClass]: * source

### public [_autoShadow]: * source

### public [_checkpoint]: {"data": *} source

### public [_impl]: * source

### public [_initialState]: * source

### public [_mixins]: *[] source

### public [_parent]: * source

### public [_pid]: * source

### public [_readonly]: * source

### public [_shader]: * source

### public [_stateType]: * source

### public [_store]: * source

## Public Methods

### public $$(): Property source

Use this.$$() in shadow methods to get access to the property. Useful in `Property` subclass `@shadow` methods since the method will be bound to the shadow. Exposing on the `Property` allows for the same code to work when called as a member function using `this` or called through a shadow function.

#### Return:

Property | the property instance (`this`)

### public autoShadow(): boolean source

Gets if autoshadowing is enabled for this property. Unlike the Property#readonly shadowing attribute, autoshadowing is not hierarchically determined.

#### Return:

boolean | true if autoshadowing is enabled

### public checkpoint() source

Copies the current actual state for later reset using Property#resetToCheckpoint. An existing checkpoint will take precedence over subsequent calls.

### public clearCheckpoint() source

Clears an existing checkpoint created using Property#checkpoint.

### public create$(impl: *): Access source

Creates the object to be assigned to the shadow.$ property. Subclasses can override this method to setup a chain of specialized accessors (`$()`). See Access for details on setting up specialized accessors. This is an advanced feature and rarely required.

#### Params:

Name | Type | Attribute | Description
impl | * |  |

#### Return:

Access | a property accessor instance.

### public dotPath(): string source

Gets the path from root property using a dot (`.`) separator. Suitable for using with the lodash `result()` function.

#### Return:

string | path with each component joined by a `.`

#### See:

- https://lodash.com/docs/4.17.4#result

### public getCheckpoint(): * source

Gets the checkpoint state previously recorded using Property#checkpoint.

#### Return:

* | the checkpoint data if checkpoint is set.

### public getInitialState(state: *): * source

Gets the initial state for a property at the beginning of the property mounting process. This implementation merges the StateType#initialStateWithDefaults, the initial state set using #setInitialState, and the state passed in from the existing store state. The store's state property values take precedence. The explicitly set initial state is used only when the `state` parameter is `undefined`.

#### Params:

Name | Type | Attribute | Description
state | * |  | the store's property state at the time of mounting.

#### Return:

* | merged state with the state parameter taking precedence if the initial state is set otherwise returns the state parameter. This base implementation simply returns the state parameter

### public hasCheckpoint(): boolean source

Gets if an existing checkpoint has be created using Property#checkpoint.

#### Return:

boolean | true if a checkpoint has been recorded.

### public initialState(): * source

Gets the result from StateType#computeInitialState.

#### Return:

*

### public isActive(): boolean source

Gets if the property is currently shadowing an actual state property.

#### Return:

boolean

### public isIsolated(): boolean source

Gets if property is an actual isolated property managed by the store. This implementation always returns false. Override to change behavior.

#### Return:

boolean

### public isReadonly(): boolean source

Gets if the property allows for assignment through the shadow state, ie `todo.desc = "go skiing"`. The readonly attribute is hierarchically determined through the parent property if not explicitly set.

#### Return:

boolean | true if assignment is not allowed

### public isRoot(): boolean source

Gets if this is the shadow state root property.

#### Return:

boolean | true if this is the root property of the Store managing the application state.

### public name(): string | number source

The property name by which this property is referenced by the Property.parent.

#### Return:

string | number | the name or `undefined` if not active. A `string` for an object child property and a `nuber` for an array element.

### public nextState(): * source

Gets what the actual state for this property will be after the Store updates all pending actions.

#### Return:

* | the next state or `undefined` if not active.

### public owner(): Property source

Gets the object containing or managing this property. All properties have an owner except the root property. Isolated properties are a case where a property is independently managed by the store so it can have an owner but not a parent.

#### Return:

Property | alias for Property#parent

### public parent(): Property source

Gets the parent property.

#### Return:

Property | the parent property or `undefined` if this is the shadow state root.

### public parentShadow(): Shadow source

Gets the parent's shadow property.

#### Return:

Shadow

### public path(): [] source

Gets the Property#name components from the root property to this property.

#### Return:

[] | array where each name component is either a `string` or `number` depending on the each parent component's type.

### public pid(): number source

Gets the unique f.lux ID for this property.

#### Return:

number | the id

### public propertyChildInvalidated(childProperty: Property, sourceProperty: Property) source

A child property or one of its descendents wil be changing state. Useful hook when a property needs to perform some bookkeepng for child properties. Utilizing this hook provides a chance to make tracking changes in shadow properties before the store updates its state.

Subclasses do not need to invoke the parent implementation.

#### Params:

Name | Type | Attribute | Description
childProperty | Property |  | the immediate child property through which the update is occurring.
sourceProperty | Property |  | the property generating the property change.

### public propertyDidShadow() source

Invoked by the f.lux shadowing process after a property initially shadows a state property. The property is active and can safely access the shadow state.

Subclasses do not need to invoke the parent implementation.

### public propertyDidUpdate() source

Invoked by the f.lux shadowing process after a property is reshadowed.

Subclasses do not need to invoke the parent implementation.

### public propertyWillShadow() source

Invoked by the f.lux shadowing process just before a property initially shadows a state property. The property is not active when this method is invoked so state values cannot be accessed. This method is useful for constructor type activities when you do not want to implement a constructor.

Subclasses do not need to invoke the parent implementation.

### public propertyWillUnshadow() source

Invoked by the f.lux shadowing process just before a property will be removed from the shadow state.

Subclasses do not need to invoke the parent implementation.

### public resetToCheckpoint() source

Replaces the current property state with a checkpoint state previously recorded using Property#checkpoint. The checkpoint is cleared.

### public root(): Property source

Gets the shadow state root property for the Store managing this property.

#### Return:

Property | the root property

### public rootShadow(): Shadow source

Gets the root shadow state for the Store managing this property.

#### Return:

Shadow

### public setAutoshadow(auto: boolean): * source

Sets the auto shadow property flag.

Note: this method is rarely required as the StateType will usually configure this attribute.

#### Params:

Name | Type | Attribute | Description
auto | boolean |  | boolean where true means to auto map subproperties.

#### Return:

* | reference to this property object.

### public setImplementationClass(ImplClass: *) source

#### Params:

Name | Type | Attribute | Description
ImplClass | * |  |

### public setInitialState(state: *): Property source

Explicitly sets an initial state that will be used if the state tree does not have a value for this property. This value is used by Property#getInitialState and is merged using StateType#initialStateWithDefaults.

Note: this method is rarely required as the StateType will usually configure this attribute.

#### Params:

Name | Type | Attribute | Description
state | * |  | the initial state for the property

#### Return:

Property | reference to this property object.

### public setReadonly(readonly: *) source

Sets the readonly flag which will prevent an assignment from changing the value. More technically, a 'set' function being set in the implementation's defineProeprty().

Note: this method is rarely required as the StateType will usually configure this attribute.

#### Params:

Name | Type | Attribute | Description
readonly | * |  |

### public setShadowClass(ShadowClass: Shadow) source

Sets the class to be used for the shadow api

#### Params:

Name | Type | Attribute | Description
ShadowClass | Shadow |  | the Shadow class or one of its subclasses

### public shader(state: *): * source

Gets the Shader instance for this property.

#### Params:

Name | Type | Attribute | Description
state | * |  |

#### Return:

*

### public shadowClass(): * source

Returns the Shadow subclass used to virtualize the state property.

Returns - Shadow class

#### Return:

*

### public slashPath(): string source

Gets the path from root property using a slash (`/`) separator.

#### Return:

string | path with each component separated by a `/`

### public state(): * source

Gets the actual state being shadowed.

#### Return:

*

### public stateType(): * source

Gets the StateType used for creating this property.

#### Return:

*

### public store(): * source

Gets the {@Link Store} containing the application state.

#### Return:

*

### public touch() source

Triggers a reshadow of the properties shadow state. This is handy when a calculated state value changes while concrete state values remain unchanged.

### public typeName(): * source

Gets this property's StateType.typeName value.

#### Return:

*

### public update(callback: function) source

Makes changes to the next proeprty state. The callback should be pure (no side affects).

The callback has the form:

    function callback(state) : { name, nextState, replace }

where:

- `state` - the current state
- `nextState` - the next state for the property
- `name` - the name of the action, such as "assign()" (optional)
- `replace` - should the entire state for this property be replaced with `nextState`. A value of `true` means this property will unshadow and all of it's children will not be able to make future changes to the model. (optional - default=false)

The callback return value is called an action descriptor and describes the update behavior.To understand the reasoning behind the replace flag consider the following example:

``` const model = { a: { b: { c: 1 } } } const oldB = model.a.b

model.a.b = "foo" oldB.c = 5

model.a.b.c === undefined ```js

Thus, oldB.c may change oldB'c property 'c' to 5 but model.a.b is still "foo".

#### Params:

Name | Type | Attribute | Description
callback | function |  | takes the current state and returns an object containing the action descriptor (see discussion above). At a minimum, the action descriptor must contain a `nextState` property containing the property's state following the action.