import Input from 'mebo/src/Input.js'

public class | source

Input

Direct Subclass:

Any, BaseText, Bool, Buf, Numeric, Stream, Timestamp

Indirect Subclass:

Email, FilePath, Hash, Hex, Ip, Text, UUID, Url, Version

An input holds a value that is used for the execution of the Action.

The value carried by the input gets checked through a wide range of validations that make sure the value meets the necessary requirements for the execution of the Action.

The validations are performed asynchronously which enables an implementation that can go far beyond checking the data type or matching the value through a regex. In most cases these validations are driven by properties. Properties are usually defined at construction time. Also, non-generic validations can be implemented through extendedValidation, making possible to define validations that are tied with an action itself.

Inputs are created through Input.create using a syntactic sugar that describes their name and type (aka TypeScript), for instance:

Input.create('myInput: bool')

Any input can be defined as a vector by using the short array syntax []:

Input.create('myInput: bool[]')

In case you want to hide specific inputs from readers (Reader), you can use the prefix _ in the input name. By doing that the input is automatically assigned as hidden (same effect as setting the property hidden=true at the construction of the input):

Input.create('_myInput: bool[]')

Additionally, you can specify if an input is optional (not required) by adding ? beside of the input name:

Input.create('myInput?: bool[]')

You can also create inputs through a verbose (boilerplate) interface where each of the options described above can be defined at construction time via properties:

Input.create('myInput', {type: 'bool', vector: true, required: false, hidden: false})

Since inputs are used by actions they can be created directly inside of an Action via Action.createInput that internally triggers Input.create factory method:

class HelloWorld extends Mebo.Action{
  constructor(){
    super();
    // ♥ compact version
    this.createInput('myInputA?: bool[]');

    // same as effect as above, but not so friendly to read
    this.addInput(Input.create('myInputB?: bool[]'));
  }
}

To register a new input type, take a look at Input.register

Property Summary

Property Name	Description	Default Value
required	boolean telling if the value is required (defined at the construction time)
immutable	boolean telling if the data of the value cannot be altered overtime, however the value of the input can still be replaced by the input value setter, in order to prevent it you can set an input as readOnly
defaultValue	default value of the input
elementType	tells how the input should be presented via Cli: `'option'` or `'argument'` (http://docopt.org)	`'option'`
vector	boolean telling if the input holds a vector value (defined at the construction time)
hidden	boolean telling if the input is hidden from the Reader, therefore it should only be used internally
autofill	key name about a value that may be under the Session.autofill. This value is used to initialize the input. It occurs when a session is assigned to an action (Action.setSession)
description	description about the input. This information is displayed when showing the help about the action
shortOption	short version of the input name used to speficy when running through the Cli

The assignment of a property value can be done at construction time or through the setter Input.assignProperty. A property value can be queried by the getter Input.property. To add new properties to an input type, please take a look at Input.registerProperty.

Static Method Summary

Static Public Methods
public static	create(inputInterface: string, properties: Object, extendedValidation: function): Input Creates an input instance.
public static	register(inputClass: Input, name: string) Registers a new input type to the available inputs
public static	registerProperty(inputClassOrRegisteredName: string \| Input, name: string, initialValue: *) Registers a property for the input type (also available as `Mebo.Input.registerProperty`)
public static	registeredInput(name: string): Input Returns the input type based on the registration name
public static	registeredInputNames(): Array<string> Returns a list containing the names of the registered input types
public static	registeredPropertyNames(inputClassOrRegisteredName: string \| Input): Array<string> Returns a list about all registered property names including the inherited ones for the input type

Static Protected Methods
protected static	_decodeScalar(value: string): * Decodes the input value from the string representation (Input._encodeScalar) to the data type of the input.
protected static	_decodeVector(value: string): * Decodes a vector value from the string representation ({Input._encodeScalar & Input._encodeVector) to the data type of the input.
protected static	_encodeScalar(value: *): string Encodes the input value to a string representation that can be later decoded through Input._decode.
protected static	_encodeVector(values: Array<string>): string Encodes a vector value to a string representation that can be later decoded through Input._decodeVector.

Constructor Summary

Public Constructor
public	constructor(name: string, properties: Object, extendedValidation: function) Creates an input

Method Summary

Public Methods
public	assignProperty(name: string, value: *, loose: boolean) Sets a property to the input.
public	cache(): ImmutableMap Returns the cache used by the input
public	clearCache() Forces to flush the internal input cache
public	hasProperty(name: string): boolean Returns a boolean telling if the input property name is assigned to the input
public	isEmpty(): boolean Returns if the value of the input is empty.
public	isPropertyLocked(name: string): boolean Returns a boolean telling if the property is locked (Input.lockProperty)
public	isRequired(): boolean Returns if the value of the input is required.
public	isSerializable(): boolean Returns if the input is serializable
public	isVector(): boolean Returns if the value of the input is a vector.
public	lockProperty(name: string, lock: boolean) Prevents a property value to be modified by Input.assignProperty
public	name(): string Returns the name of the input which is defined at construction time (inputs cannot be renamed)
public	parseValue(value: string, assignValue: boolean): * Decodes a value represented as string to the type that is compatible with the input.
public	property(name: string): Promise<*> Returns the property value for the input property name
public	propertyNames(): Array<string> Returns a list containing the property names assigned to the input
public	readOnly(): boolean Returns a boolean telling if the input is in read-only mode.
public	async serializeValue(): Promise<string> This method should return a string representation about the current value in a way that can be recovered later through parseValue.
public	setReadOnly(enable: boolean) Changes the read-only state of the input.
public	setValue(value: *) Sets the value of the input
public	setupFrom(sourceInput: Input, at: null \| number, cache: boolean) Sets the input value by avoiding the overhead that may occur when the same value is used across actions that have the input type, therefore this method avoids the re-computation by copying the caches and value associated with the source input to the current input.
public	async validate(): Promise<*> Executes the input validations (_validation), in case of a failed validation then an exception of type ValidationFail is raised
public	value(): * Returns the value of the input
public	valueAt(index: number): * This method enforces the context of the value being queried.

Protected Methods
protected	_getFromCache(name: string, at: null \| number): * Auxiliary method used internally by the input implementations to get a value from the cache
protected	_isCached(name: string, at: null \| number): boolean Auxiliary method used internally by input implementations to check if the key is under the cache
protected	_setToCache(name: string, value: *, at: null \| number) Auxiliary method used internally by input implementations to set a value to the cache
protected	async _validation(at: null \| number): Promise<*> Use this method to implement generic validations for your input implementation.

Static Public Methods

public static create(inputInterface: string, properties: Object, extendedValidation: function): Input source

Creates an input instance.

Params:

Name	Type	Attribute	Description
inputInterface	string		string followed by either the pattern `name: type` or `name?: type` in case of optional Input. The type is case-insensitive
properties	Object	optional default: {}	plain object containing the properties which will be assigned to the Input
extendedValidation	function	optional	callback that can be defined to supply custom validations to the Input

Return:

Input

Example:

// minimal
Input.create('inputName: numeric');

// full
Input.create('inputName: numeric', {min: 1, max: 5}, function(at){
 return new Promise((resolve, reject) => {
   if (this.valueAt(at) === 3)
     reject(new ValidationFail('Failed for some reason'));
   else
     resolve(this.value());
 });
})

public static register(inputClass: Input, name: string) source

Registers a new input type to the available inputs

Params:

Name	Type	Attribute	Description
inputClass	Input		input implementation that will be registered
name	string	optional	string containing the registration name for the input. In case of an empty string, the registration is done by using the name of the type (this information is stored in lowercase)

public static registerProperty(inputClassOrRegisteredName: string | Input, name: string, initialValue: *) source

Registers a property for the input type (also available as Mebo.Input.registerProperty)

// example of registering a new property
Mebo.Input.registerProperty('text', 'myCustomProperty', 'A initial value if necessary')

Params:

Name	Type	Attribute	Description
inputClassOrRegisteredName	string \| Input		registered input name or input class in which the property should be registered
name	string		name of the property (in case the property name already exists than it going to be overridden for the input type)
initialValue	*	optional	optional initial value for the property (undefined by default)

public static registeredInput(name: string): Input source

Returns the input type based on the registration name

Params:

Name	Type	Attribute	Description
name	string		name of the registered input type

Return:

Input

public static registeredInputNames(): Array<string> source

Returns a list containing the names of the registered input types

Return:

Array<string>

public static registeredPropertyNames(inputClassOrRegisteredName: string | Input): Array<string> source

Returns a list about all registered property names including the inherited ones for the input type

// returning all properties for an input type (using 'numeric' as example)
Mebo.Input.registeredPropertyNames('numeric');

Params:

Name	Type	Attribute	Description
inputClassOrRegisteredName	string \| Input		registered input name or input class

Return:

Array<string>

Static Protected Methods

protected static _decodeScalar(value: string): * source

Decodes the input value from the string representation (Input._encodeScalar) to the data type of the input. This method is called internally during Input.parseValue

Params:

Name	Type	Attribute	Description
value	string		encoded value

Return:

protected static _decodeVector(value: string): * source

Decodes a vector value from the string representation ({Input._encodeScalar & Input._encodeVector) to the data type of the input. This method is called internally during Input.parseValue

Params:

Name	Type	Attribute	Description
value	string		encoded value

Return:

protected static _encodeScalar(value: *): string source

Encodes the input value to a string representation that can be later decoded through Input._decode. This method is called internally during the serializeValue

Params:

Name	Type	Attribute	Description
value	*		value that should be encoded to a string

Return:

string

protected static _encodeVector(values: Array<string>): string source

Encodes a vector value to a string representation that can be later decoded through Input._decodeVector. This method is called internally during the serializeValue

Params:

Name	Type	Attribute	Description
values	Array<string>		value that should be encoded to a string

Return:

string

Public Constructors

public constructor(name: string, properties: Object, extendedValidation: function) source

Creates an input

Params:

Name	Type	Attribute	Description
name	string		name of the input
properties	Object	optional default: {}	plain object containing the properties which will be assigned to the Input
extendedValidation	function	optional	callback that can be defined to supply custom validations to the Input

Public Methods

public assignProperty(name: string, value: *, loose: boolean) source

Sets a property to the input. In case the property already exists then the value is going to be overridden. By default the only properties that can be modified are the ones found under Input.registeredInputNames. However you can assign a non-registered property by enabling loose parameter.

Property values can be locked, therefore preventing modifications (Input.lockProperty).

Params:

Name	Type	Attribute	Description
name	string		name of the property
value	*		value for the property
loose	boolean	optional default: false	when true lets to assign a property that is not registered to the input (Input.registeredInputNames)

public cache(): ImmutableMap source

Returns the cache used by the input

This method is called by (setupFrom) to setup the input based on an already existing input

Return:

ImmutableMap

public clearCache() source

Forces to flush the internal input cache

public hasProperty(name: string): boolean source

Returns a boolean telling if the input property name is assigned to the input

Params:

Name	Type	Attribute	Description
name	string		name of the property

Return:

boolean

public isEmpty(): boolean source

Returns if the value of the input is empty. This is used mainly by the property required=false to know if the input does not have a value assigned to it.

Return:

boolean

If the input is empty

public isPropertyLocked(name: string): boolean source

Returns a boolean telling if the property is locked (Input.lockProperty)

Params:

Name	Type	Attribute	Description
name	string		name of the property

Return:

boolean

public isRequired(): boolean source

Returns if the value of the input is required. This information is defined by the property required=true

Return:

boolean

if the input is required

public isSerializable(): boolean source

Returns if the input is serializable

This method should be re-implemented by derived classes to tell if the input can be serialized (default true).

In case of a serializable input, the methods Input._encodeScalar and Input._decode are expected to be implemented.

Return:

boolean

public isVector(): boolean source

Returns if the value of the input is a vector. This information is defined by the property vector=true

Return:

boolean

if the input is a vector

public lockProperty(name: string, lock: boolean) source

Prevents a property value to be modified by Input.assignProperty

Params:

Name	Type	Attribute	Description
name	string		name of the property
lock	boolean	optional default: true	if true it locks the property otherwise it removes the lock from the property

public name(): string source

Returns the name of the input which is defined at construction time (inputs cannot be renamed)

Return:

string

public parseValue(value: string, assignValue: boolean): * source

Decodes a value represented as string to the type that is compatible with the input. This method is called by the Handler or when an action is loaded/created using Action.fromJSON/Action.createFromJSON. In case the input is defined as vector then the value can be defined using an array encoded in JSON. The parsed value gets returned and assigned to the input as well (you can control this by the assignValue argument).

The implementation of the decoding is done by the methods Input._decode & Input._decodeVector. To know if an input supports decoding checkout the Input.isSerializable.

To know how the serialization is done for the inputs bundled with Mebo take a look at Reader documentation.

Params:

Name	Type	Attribute	Description
value	string		string containing the serialized data
assignValue	boolean	optional default: true	tells if the parsed value should be assigned to the input

Return:

public property(name: string): Promise<*> source

Returns the property value for the input property name

Params:

Name	Type	Attribute	Description
name	string		name of the property

Return:

Promise<*>

The value of the property otherwise raises an exception in case the property is not assigned

public propertyNames(): Array<string> source

Returns a list containing the property names assigned to the input

Return:

Array<string>

public readOnly(): boolean source

Returns a boolean telling if the input is in read-only mode. A read-only input cannot have its value and properties modified

Return:

boolean

public async serializeValue(): Promise<string> source

This method should return a string representation about the current value in a way that can be recovered later through parseValue.

The encode implementation is done by the methods Input._encodeScalar & Input._encodeVector. To know if an input supports serialization checkout the Input.isSerializable.

Also, in case you want to know the serialization form for the inputs bundled with Mebo checkout Reader.

Return:

Promise<string>

public setReadOnly(enable: boolean) source

Changes the read-only state of the input. A read-only input cannot have its value and properties modified. It's mainly used during the execution of the Action where all inputs are assigned as read-only, therefore when the execution is completed the inputs are restored with the original read-only value assigned before the execution of the action

Params:

Name	Type	Attribute	Description
enable	boolean		tells if a input is read-only

public setValue(value: *) source

Sets the value of the input

Params:

Name	Type	Attribute	Description
value	*		value that should be set to the input

public setupFrom(sourceInput: Input, at: null | number, cache: boolean) source

Sets the input value by avoiding the overhead that may occur when the same value is used across actions that have the input type, therefore this method avoids the re-computation by copying the caches and value associated with the source input to the current input. The cache will be only copied if both source and target inputs have the immutable property enabled (default true).

Params:

Name	Type	Attribute	Description
sourceInput	Input		input used as source to setup the current input
at	null \| number	optional	index used when the target input is defined as vector to tells which value should be used
cache	boolean	optional default: true	tells if the cache will be copied as well

public async validate(): Promise<*> source

Executes the input validations (_validation), in case of a failed validation then an exception of type ValidationFail is raised

Return:

Promise<*>

Returns the value of the input

public value(): * source

Returns the value of the input

Return:

public valueAt(index: number): * source

This method enforces the context of the value being queried. Since the input can behave as vector it makes sure that when that's the case the index must be supplied otherwise it raises an exception. Use this method when you need to query the value through validations where the index (at) is always passed to them, whether if the input is vector or scalar

Params:

Name	Type	Attribute	Description
index	number	optional	used when the input is set to a vector to tell the index of the value

Return:

Protected Methods

protected _getFromCache(name: string, at: null | number): * source

Auxiliary method used internally by the input implementations to get a value from the cache

Params:

Name	Type	Attribute	Description
name	string		name of the key
at	null \| number	optional	used when the input is set to a vector to tell the index of the value

Return:

protected _isCached(name: string, at: null | number): boolean source

Auxiliary method used internally by input implementations to check if the key is under the cache

Params:

Name	Type	Attribute	Description
name	string		name of the key
at	null \| number	optional	used when the input is set to a vector to tell the index of the value

Return:

boolean

protected _setToCache(name: string, value: *, at: null | number) source

Auxiliary method used internally by input implementations to set a value to the cache

Params:

Name	Type	Attribute	Description
name	string		name of the key
value	*		value that should be set in the cache
at	null \| number	optional	used when the input is set to a vector to tell the index of the value

protected async _validation(at: null | number): Promise<*> source

Use this method to implement generic validations for your input implementation. In case any validation fails this method should return a ValidationFail (This method is called when the validations are perform through Input.validate)

Params:

Name	Type	Attribute	Description
at	null \| number		index used when input has been created as a vector that tells which value should be used

Return:

Promise<*>

Returns the value of the input