This addon provides a decorator that allows you to declaratively specify component arguments. Through it, you can have run-time type checking of component usage.
import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';
export default class ExampleComponent extends Component {
@argument('string')
arg = 'default';
}
For each property that your component should be given, the @argument
decorator should be applied to the property definition. It is passed a "type", which you can read more about below.
When rendering a component that uses @argument
, the initial value of the property will be validated against the given type. Each time the property is changed, the new value will also be validated. If a mismatch is found, an error is thrown describing what went wrong.
In addition, any unexpected arguments to a component will also cause an error.
The @argument
decorator takes a definition for what kind of value the property should be set to. Usually, this will represent the type of the value.
For primitives types, the name should be provided as a string (as with string
in the example above). The available types match those of Typescript, including:
any
boolean
null
number
object
string
symbol
undefined
There are also a number of helpers that can be used to validate against a more complex or specific type:
arrayOf
: Produces a type for an array of specific typesoneOf
: Produces a type that literally matches one of the given stringsoptional
: Produces an optional / nullable type that, in addition to the type that was passed in, also allowsnull
andundefined
.shapeOf
: 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)unionOf
: Produces a union type from the specified types
import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';
import {
arrayOf,
oneOf,
optional,
shapeOf,
unionOf
} from '@ember-decorators/argument/types';
export default class ExampleComponent extends Component {
@argument(arrayOf('string'))
stringArray;
@argument(oneOf('red', 'blue', 'yellow'))
primaryColor;
@argument(optional(Date))
optionalDate;
@argument(shapeOf({ id: 'string' }))
objectWithId;
@argument(unionOf('number', 'string'))
numberOrString;
}
In addition, this library includes several predefined types for convenience:
Action
- Type alias forFunction
, to be used when passing a "closure action" into a componentClassicAction
- Union ofstring
andFunction
, to be used if your component usessendAction
to invoke a "classic action"Element
- Fastboot safe type alias forwindow.Element
Node
- Fastboot safe type alias forwindow.Node
These types can also be imported from @ember-decorators/argument/types
The @argument
decorator can also take a class constructor to validate that the property value is an instance of that class
import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';
class Task {
constructor() {
this.complete = false;
}
}
export default class TaskComponent extends Component {
@argument(Task)
task;
}
Passing a class works with all of the type helpers mentioned above.
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
Type: Array
or Object
| Default: []
Once @argument
has been applied to a component, unexpected arguments passed to a component will result in an error. In order to work with some addons that expect you to provide additional arguments to your components, you can whitelist additional properties that should be ignored.
When provided an array of string
, those exact properties will be added to the whitelist.
To provide a more flexible solution, you can also provide an object with the following structure:
shapeOf({
// Whitelist any string starting with one of these values
startsWith: optional(arrayOf('string'))
// Whitelist any string ending with one of these values
endsWith: optional(arrayOf('string'))
// Whitelist any string that include one of these values anywhere
includes: optional(arrayOf('string'))
// Whitelist any string that exactly matches one of these values
matches: optional(arrayOf('string'))
})
// config/environment.js
module.exports = function(environment) {
let ENV = {
// ...
'@ember-decorators/argument': {
argumentWhitelist: {
startsWith: ['hotReloadCUSTOM']
}
}
};
// ...
return ENV;
};
Type: Boolean
| Default: true
By default most of the code provided by this addon is removed in a Production build of your application. This way you can create a great development experience when writing your application, but prevent your users from paying the download or runtime cost of the validation. Both the runtime of the library, and any usage of the @argument
decorator in your code, will be removed.
However, if the process seems buggy or you want the validation in production, setting this flag to false
will prevent any code from being removed.
// ember-cli-build.js
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
module.exports = function(defaults) {
let app = new EmberApp(defaults, {
'@ember-decorators/argument': {
enableCodeStripping: false
}
});
return app.toTree();
};
This addon works out-of-the-box with Ember 3.6
and higher. This is due to a dependency on the changes to the native class constructor behavior that landed in that Ember version.
Support can be polyfilled using ember-native-class-polyfill
back to any version that it supports. Currently, that is Ember 3.4
.
ember serve
- Visit your app at http://localhost:4200.
npm test
npm run test:all
(Runsember try:each
to test your addon against multiple Ember versions)ember test --server
ember build
For more information on using ember-cli, visit https://ember-cli.com/.