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

public class | source

# StateType

Defines the shadowing behavior for a property. f.lux uses StateType instances to configure Shader instances that are then used to proxy the store's state using shadow properties.

Property subclasses usually expose a `type`'`class variable to specify their default shadowing behavior. The`type`class variable should be a getter property and is typically attached to the class using the`StateType.defineType()`` function.

Example of defining a `type` class variable:

    StateType.defineType(TodoRootProperty, type => {
    ‌    type.initialState({})                           // empty object initial state
    ‌        .autoshadowOff                          // do not shadow state values without explicit definitions
    ‌        .properties({                           // define sub-properties (just one in this case)
    ‌            todos: TodoCollection.type,     // 'todos' is a collection property
    ‌        })
    ‌        .readonly                               // prevent reassigning the 'todos' collection (paranoia)
    ‌        .typeName("TodoRootProperty");          // useful for certain diagnostic situations
    });

Shadowing behavior may be customized by setting the following StateType values:

- autoshadow - shadow implicit state properties using default f.lux property types (default=true)
- defaults - specifies default values for an object's initial state. A default value is applied when the initial state for this property is 'undefined'. (default=undefined)
- element type - StateType used for shadowing each sub-property, such as elements in an array or properties of an object. (default=null)
- jit properties - dynamically extends the 'properties' based on the property's state through a callback function (experimental)
- implementation class - ShadowImpl subclass used to back shadow state property (default=null)
- initial state - the initial property value. The store's state will take precedence and this value is used when the store's state is undefined for the specific property. (default=undefined)
- managed type - StateType instance used by CollectionProperty to specify the property type for each model contained in the collection. Other collection types could utilize the same mechanism. (default=null)
- properties - literal object with name/value pairs where name is the sub-property name and the value is a StateType instance describing the property shadowing behavior (default={})
- shadow class - Shadow subclass used to represent a shadow state property. Built-in implementation classes set a default so only need to set when want to customize parent type default. (default=null)

Methods/properties used when setting up a `StateType` description:

- `addProperty(name, type)` - add a single property type where 'name' is the sub-property name and value is a StateType. Consider using StateType.properties() instead.
- `autoshadow` - turn on auto-shadowing (default)
- `autoshadowOff` - turn off auto-shadowing
- `default(state)` - used with ObjectProperty and MapProperty sub-properties to set defaults for values. The default value is only applied if the initial state for this property is undefined. Example usage:

      stateType.properties({
      ‌    name: PrimitiveProperty.type.default(null),
      })

- `elementType(type)` - StateType for shadowing each sub-property. Regularly used with IndexedProperty and ArrayProperty. Used with ObjectProperty and MapProperty when each value is the same type such as in a dictionary.
- `jitProperties(callback)` - Sets a callback used for dynamically extending properties definition. Callback signature is 'callback(state, parentProperty)' and returns object with name/value pairs where name is the sub-property name and the value is a StateType instance describing the property shadowing behavior. (advanced feature)
- `implementationClass(cls)` - sets the ShadowImpl subclass to be used for backing the shadow state (should not be needed)
- `initialState(state)` - value suitable for the property type: boolean, array, object,...
- `managedType(type)` - StateType for shading managed properties (used with CollectionProperty) Example usage:

      stateType.managedType(TodoProperty.type)

- `properties(propTypes)` - add multiple properties using a literal object with property-name/StateType key/value pairs Example usage:

      stateType.properties({
      ‌    completed: PrimitiveProperty.type.initialState(false),
      ‌    created: PrimitiveProperty.type.readonly,
      ‌    desc: PrimitiveProperty.type,
      ‌    id: PrimitiveProperty.type.readonly,
      })

- `readonly` - set property to readonly
- `readonlyOff` - set property to read/write (default unless parent property has set readonly to true since readonly property cascades through the state tree)
- `typeName(name)` - set a label for the type. Useful for debugging situations where shadowing is not acting as expected. Example usage:

      const root = store.shadow;
      const rootProperty = root.$$();

      console.log(rootProperty.typeName());
      console.log(rootProperty.stateType().getTypeName());

Instances of this class are rarely directly created and instead are created using the `defineType` static functions of each built-in property class.

#### See:

- ArrayProperty
- CollectionProperty
- IndexedProperty
- MapProperty
- ObjectProperty

## Static Method Summary

Static Public Methods
public static | create(PropertyClass: Property): * Convenience class method to avoid using 'new StateType(...)' making chaining on the newly created StateType easier to read. |
public static | defineType(PropertyClass: Property, typeCallback: function): * Sets a `type` getter on a Property class. |
public static | defineTypeEx(PropClass: Property, ShadowType: Shadow, typeCallback: function, initialState: *) Sets a `type` getter on a Property class with the ability to set the initial state. |
public static | from(prop: Property): * Walks the prototype chain and returns the first StateType returned by a `type` class variable. |
public static | implementationClassForProperty(property: Property, defaultClass: ShadowImpl): * Determines the ShadowImpl subclass to use for the property. |

## Constructor Summary

Public Constructor
public | constructor() |

## Member Summary

Public Members
public get | autoshadow: StateType: * Shadowing configuration getter to enable auto-shadowing. |
public get | autoshadowOff: StateType: * Shadowing configuration getter to disable auto-shadowing. |
public get | readonly: StateType: * Shadowing configuration getter to set the readonly attribute. |
public get | readonlyOff: StateType: * Shadowing configuration getter to disable the readonly attribute. |

## Method Summary

Public Methods
public | accessClass(Cls: *): * |
public | addProperty(name: string, type: StateType): StateType Shadowing configuration method to add a child property. |
public | clone(): StateType Creates a shallow copy of this `StateType` |
public | computeInitialState(): * Generates the initial state for this property and its immediate child properties. |
public | default(state: *): StateType Sets the default property values for child properties. |
public | elementType(type: StateType): StateType Sets the `StateType` to use for shadowing each immediate child property. |
public | getTypeName(): string Gets the descriptive type name from the StateType#_PropertyClass. |
public | implementationClass(cls: *): StateType The ShadowImpl class to use for backing the properties Shadow. |
public | initialState(state: *): StateType Sets the initial state for the property if the f.lux store's state does not have a value for this property. |
public | initialStateWithDefaults(state: *): * Generates the initial state for this property and its immediate child properties. |
public | jitProperties(callback: function): * Sets a callback used for dynamically extending the child property definitions. |
public | managedType(type: StateType): StateType Sets the `StateType` for the 'managed type'. |
public | properties(propTypes: *): StateType Sets `StateType` values describing the shadowing behavior for multiple child properties. |
public | propertyClass(PropertyClass: Property): StateType Sets the Property class used for shadowing the state property. |
public | shadowClass(cls: Shadow): StateType Sets the Shadow class to be used for shadowing the property. |
public | typeName(name: *): StateType Sets a descriptive type name on a property class. |

## Static Public Methods

### public static create(PropertyClass: Property): * source

Convenience class method to avoid using 'new StateType(...)' making chaining on the newly created StateType easier to read.

#### Params:

Name | Type | Attribute | Description
PropertyClass | Property |  | a Property class (not object) that shadowing behavior is being defined.

#### Return:

*

### public static defineType(PropertyClass: Property, typeCallback: function): * source

Sets a `type` getter on a Property class. The `type` getter is used to define properties in the StateType#properties method. The `type` getter may be set once per class and all further requests are ignored.

Example usage:

    StateType.defineType(CounterProperty);
    ‌
    // and the use it
    ‌
    ObjectProperty.createClass({}, type => {
    ‌    type.properties({
    ‌        counter: CounterProperty.type.readonly,
    ‌    })
    });

#### Params:

Name | Type | Attribute | Description
PropertyClass | Property |  | the Property subclass on which to define the `type` getter
typeCallback | function |  | callback of form `cb(type)` that allows the StateType to be customized

#### Return:

*

### public static defineTypeEx(PropClass: Property, ShadowType: Shadow, typeCallback: function, initialState: *) source

Sets a `type` getter on a Property class with the ability to set the initial state. The `type` getter is used to define properties in the StateType#properties method. The `type` getter may be set once per class and all further requests are ignored.

#### Params:

Name | Type | Attribute | Description
PropClass | Property |  | Property subclass (required)
ShadowType | Shadow | optional | Shadow subclass or will pick up default set by parent class
typeCallback | function |  | callback of form `cb(type)` that allows the StateType to be customized
initialState | * | optional | the initial state for the new property.

### public static from(prop: Property): * source

Walks the prototype chain and returns the first StateType returned by a `type` class variable.

#### Params:

Name | Type | Attribute | Description
prop | Property |  | one of a Property instance or class `p`rototype`

#### Return:

* | the StateType describing the property

### public static implementationClassForProperty(property: Property, defaultClass: ShadowImpl): * source

Determines the ShadowImpl subclass to use for the property.

#### Params:

Name | Type | Attribute | Description
property | Property |  | the `Property` instance to check
defaultClass | ShadowImpl | optional | =ShadowImpl - the `ShadowImpl` subclass to use if one is not specified in the `type` StateType class variable for the `property` parameter.

#### Return:

*

## Public Constructors

### public constructor() source

## Public Members

### public get autoshadow: StateType: * source

Shadowing configuration getter to enable auto-shadowing. Auto-shadowing is enabled by default and the shadowing attribute does not cascade through the state hieararchy.

#### Return:

StateType | this instance for use in chaining configuration calls

### public get autoshadowOff: StateType: * source

Shadowing configuration getter to disable auto-shadowing. Auto-shadowing is enabled by default and the shadowing attribute does not cascade through the state hieararchy.

#### Return:

StateType | this instance for use in chaining configuration calls

### public get readonly: StateType: * source

Shadowing configuration getter to set the readonly attribute. Readonly is disabled by default and the attribute cascades through the state hieararchy. This means all child properties will be readonly once an upper level property's `readonly` attribute is enabled until explicitly disabled using StateType#readonlyOff.

#### Return:

StateType | this instance for use in chaining configuration calls

### public get readonlyOff: StateType: * source

Shadowing configuration getter to disable the readonly attribute. Readonly is disabled by default and the attribute cascades through the state hieararchy. This means all child properties will be readonly once an upper level property's `readonly` attribute is enabled until explicitly disabled using StateType#readonlyOff.

#### Return:

StateType | this instance for use in chaining configuration calls

## Public Methods

### public accessClass(Cls: *): * source

#### Params:

Name | Type | Attribute | Description
Cls | * |  |

#### Return:

*

### public addProperty(name: string, type: StateType): StateType source

Shadowing configuration method to add a child property. The current implementation support 'keyed' properties only, such as ObjectProperty and MapProperty.

Consider using StateType#properties for adding multiple properties.

#### Params:

Name | Type | Attribute | Description
name | string |  | the property key
type | StateType |  | the property `StateType` descriptor

#### Return:

StateType | this instance for use in chaining configuration calls

### public clone(): StateType source

Creates a shallow copy of this `StateType`

#### Return:

StateType

### public computeInitialState(): * source

Generates the initial state for this property and its immediate child properties. This method does not account for any explicit default values set using StateType#default.

#### Return:

* | the initial state

### public default(state: *): StateType source

Sets the default property values for child properties. A default value is used when the Store state and the property `type` descriptor's initial state are not defined.

#### Params:

Name | Type | Attribute | Description
state | * |  | the default state value

#### Return:

StateType | this instance for use in chaining configuration calls

### public elementType(type: StateType): StateType source

Sets the `StateType` to use for shadowing each immediate child property.

#### Params:

Name | Type | Attribute | Description
type | StateType |  | `StateType` instance

#### Return:

StateType | this instance for use in chaining configuration calls

### public getTypeName(): string source

Gets the descriptive type name from the StateType#_PropertyClass. This value is set using StateType#typeName.

#### Return:

string | the descriptive name.

### public implementationClass(cls: *): StateType source

The ShadowImpl class to use for backing the properties Shadow. This rarely required.

#### Params:

Name | Type | Attribute | Description
cls | * |  |

#### Return:

StateType | this instance for use in chaining configuration calls

### public initialState(state: *): StateType source

Sets the initial state for the property if the f.lux store's state does not have a value for this property.

#### Params:

Name | Type | Attribute | Description
state | * |  | the initial value

#### Return:

StateType | this instance for use in chaining configuration calls

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

Generates the initial state for this property and its immediate child properties. The intial state is merged with any explicit default values set using StateType#default.

#### Params:

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

#### Return:

* | the initial state

### public jitProperties(callback: function): * source

Sets a callback used for dynamically extending the child property definitions. Callback signature is:

    callback(state, parentProperty)

where:

- `state` - the parent property state
- `parentProperty` - the parent property

#### Params:

Name | Type | Attribute | Description
callback | function |  | the function to call during the shadowing process to obtain any additional property definitions beyond those statically configured.

#### Return:

* | `object` with name/value pairs where name is the sub-property name and the value is a `StateType` instance describing the property shadowing behavior.

### public managedType(type: StateType): StateType source

Sets the `StateType` for the 'managed type'. Complex Property subclasses use the managed type for determining how to shadow contained data. More common is the use of StateType#elementType to specify a `StateType` for each immediate child property.

See CollectionProperty for an example of a property employing managed types.

#### Params:

Name | Type | Attribute | Description
type | StateType |  | the `StateType` describing how to shadow each managed state value.

#### Return:

StateType | this instance for use in chaining configuration calls.

### public properties(propTypes: *): StateType source

Sets `StateType` values describing the shadowing behavior for multiple child properties.

#### Params:

Name | Type | Attribute | Description
propTypes | * |  |

#### Return:

StateType | this instance for use in chaining configuration calls

### public propertyClass(PropertyClass: Property): StateType source

Sets the Property class used for shadowing the state property.

#### Params:

Name | Type | Attribute | Description
PropertyClass | Property |  | a `Property` subclass

#### Return:

StateType | this instance for use in chaining configuration calls

### public shadowClass(cls: Shadow): StateType source

Sets the Shadow class to be used for shadowing the property.

#### Params:

Name | Type | Attribute | Description
cls | Shadow |  | The `Shadow` subclass

#### Return:

StateType | this instance for use in chaining configuration calls

### public typeName(name: *): StateType source

Sets a descriptive type name on a property class. This is accomplished by setting the `name` on the StateType#_PropertyClass constructor using a variable called `__fluxTypeName__`.

#### Params:

Name | Type | Attribute | Description
name | * |  |

#### Return:

StateType | this instance for use in chaining configuration calls