@ember-decorators/argument
This addon provides a set of decorators that allow you to declaratively specify argument and field
types and properties, such as mutability. It includes:
- The
@argument
decorator, which allows you to declare a field on a component or Ember object
as an argument it receives and provide a default value - Several validation decorators and helpers inspired by ember-prop-types
which allow you to specify runtime validations for fields
Usage
import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';
import { type } from '@ember-decorators/argument/type';
import { immutable } from '@ember-decorators/argument/validation';
export default class ExampleComponent extends Component {
@argument
@type('string')
@immutable
arg = 'default';
}
{{example-component arg="value"}}
Decorators
@argument
Declares a field as an argument of the component or object and optionally will assign a default
value unless one is passed in or provided by a superclass. By default components will throw
an error if an argument is provided but was not defined on the class. This behavior does not
apply to objects in general since they have much more varied use cases, and can be disabled via
a config option in ember-cli-build
.
import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';
export default class ExampleComponent extends Component {
@argument
arg = 'default';
}
<!-- arg === 'default' -->
{{example-component}}
<!-- arg === 'value' -->
{{example-component arg="value"}}
<!-- throws an error -->
{{example-component foo="value"}}
@type
Declares that a field must be a specific type. Accepts exactly one type, which may either be a
string that represents a primitive type, a class that the field is an instance of, or a type created
using the type helpers.
Primitive types match those of Typescript, including:
any
boolean
null
number
object
string
symbol
undefined
You can also pass null
and undefined
directly as types for convenience
Type helpers include:
unionOf
: Produces a union type from the specified typesarrayOf
: Produces a type for an array of specific typesshapeOf
: Accepts an object of key -> type pairs, and checks the shape of the field to make sure it
matches the object passed in. The validator only checks to make sure that the fields exist and are their
proper types, so it is valid for all objects which fulfill the shape (structural typing)optional
: Produces an optional / nullable type that, in addition to the type that was passed in,
also allows null
and undefined
.
import Component from '@ember/component';
import { type, arrayOf, unionOf, optional } from '@ember-decorators/argument/type';
export default class ExampleComponent extends Component {
@type(unionOf(null, 'string'))
arg = 'default';
@type(unionOf(undefined, Date))
foo;
@type(unionOf('string', 'number', Date))
bar;
@type(optional(Date))
optionalDate;
@type(unionOf(null, undefined, Date))
optionalThroughUnion;
@type(arrayOf('string'))
stringArray;
@type(arrayOf('any'))
anyArray;
@type(
arrayOf(
unionOf(
'string',
'number',
Element
)
)
)
unionArray;
}
In addition, this library includes several predefined types for convenience:
Action
- union type of string
and Function
. This is the recommended type to use for actions
as it will improve readability and in the future provide metadata for automatic documentation generationClosureAction
- Type alias for Function
. If you want to enforce strict usage of closure actions only
this is the recommended typeElement
- Fastboot safe type alias for window.Element
Node
- Fastboot safe type alias for window.Node
These types can be imported from @ember-decorators/argument/types
@required
Declares that the field is required upon instantiation. The validator runs at the end of object creation,
so the value can be provided by a subclass.
import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';
import { required } from '@ember-decorators/argument/validation';
export default class ExampleComponent extends Component {
@required
@argument
arg;
}
{{example-component arg="value"}}
<!-- throws an error -->
{{example-component}}
@immutable
Declares that the field is immutable. Validations begin after the object is created, so the value can be
changed or overridden by subclasses.
import EmberObject from '@ember/object';
import { immutable } from '@ember-decorators/argument/validation';
class ExampleClass extends EmberObject {
@immutable
field = 'value';
}
let example = ExampleClasse.create();
example.set('field', 'bar');
Installation
While ember-decorators
is not a hard requirement to use this addon, it's recommended as it adds the
base class field and decorator babel transforms
ember install ember-decorators
ember install @ember-decorators/argument
Configuration
You can tweak the following settings in your config/environment.js
under the @ember-decorators/argument
namespace:
typeRequired
Type: Boolean
| Default: false
For example
module.exports = function (environment) {
let ENV = {
...
'@ember-decorators/argument': {
typeRequired: true
}
...
If enabled, requires you to also specify a @type
for every @argument
.
Note: Enabling this option breaks addons that use @ember-decorators/argument, but chose to not specify types for their arguments. See #29 for more information.
ignoreComponentsWithoutValidations
Type: Boolean
| Default: false
For example
module.exports = function (environment) {
let ENV = {
...
'@ember-decorators/argument': {
ignoreComponentsWithoutValidations: true
}
...
If enabled, components that don't have any validations defined on them will not get validated. This is very handy, if you're adding this addon to a pre-existing codebase, since it allows you to progressively migrate your components one by one.
Running
Running Tests
npm test
(Runs ember try:each
to test your addon against multiple Ember versions)ember test
ember test --server
Building
For more information on using ember-cli, visit https://ember-cli.com/.