Property decorator for declaring for glimmer component argument runtime type checks and default values, powered by facebook/prop-types.
Class decorator for checking that only arguments with the @arg
decorator are provided to a component (e.g. prevent misspelled or invalid arguments).
ember-arg-types
provides an @arg
decorator that maps glimmer arguments to local component properties. This allows default values and type checking to be easily declared (and documented) in your component JS file.
Example:
@arg(string)
sortBy = 'id';
Instead of this:
get sortBy() {
const { sortBy = 'id' } = this.args;
assert('`sortBy` must be a string', typeof sortBy === 'string');
return sortBy;
}
It also provides an opt-in class decorator @forbidExtraArgs
that will verify that all arguments passed to the component have been registered with the @arg
. This allows you to catch easy mistakes such as misspelled or invalid arguments.
import Component from '@glimmer/component';
import { arg, forbidExtraArgs } from 'ember-arg-types';
import { string } from 'prop-types';
@forbidExtraArgs
export default class ExampleComponent extends Component {
@arg(string)
hardToRememberArgument;
}
The @arg
decorator maps this.args
values to local component properties. If a mapped argument has a value of undefined
, @arg
will return the local property's initializer value.
Here the value of this.sortBy
is the value of this.args.sortBy
, unless this.args.sortBy
is undefined
. If undefined
, the value of this.sortBy
will be 'id'
.
@arg
sortBy = 'id';
Here the value of this.id
is the value of this.args.id
, unless this.args.id
is undefined
. If undefined
, the value of this.id
will be computed by the getter.
@arg
get id() {
return guidFor(this);
}
ember-arg-types
uses the popular prop-types library for runtime type checking.
By importing type validators from prop-types, you can specify a type check parameter to @arg
:
import Component from '@glimmer/component';
import { arg, forbidExtraArgs } from 'ember-arg-types';
import { string } from 'prop-types';
@forbidExtraArgs
export default class CharacterComponent extends Component {
// `name` string arg that is required
@arg(string.isRequired)
name;
}
You can find more information on prop-type
validators here: Prop Type Usage Docs
If an argument value fails a validation check, an Error
will be thrown (in non-prod environments) by default. To disable throwing Error
s , update your config/environment.js
with the following:
'ember-arg-types': {
// Throw errors instead of logging (default is true)
throwErrors: false
}
Since component type checks are not typically performed in production, prop-types replaces the library with function shims for production builds, resulting in a smaller bundle size.
ember install ember-arg-types
// components/character.js
import Component from '@glimmer/component';
import { arg, forbidExtraArgs } from 'ember-arg-types';
import { func, number, oneOf, string } from 'prop-types';
import { guidFor } from '@ember/object/internals';
const tunics = ['green', 'red', 'blue'];
@forbidExtraArgs // Asserts only @arg arguments are provided
export default class CharacterComponent extends Component {
// `id` string arg with a getter default value
@arg(string)
get id() {
return guidFor(this);
}
// `name` string arg that is required
@arg(string.isRequired)
name;
// `title` arg with default value and no type check
@arg
title = 'hero';
// `tunic` arg with set of valid string values and a default
@arg(oneOf(tunics))
tunic = tunics[0];
// `hearts` number arg with default value
@arg(number)
hearts = 12;
// `level` number arg without default value
@arg(number)
level;
// `onClick` action (function) arg with noop default value
@arg(func)
onClick = () => null;
}
- Ember.js v3.20 or above
- Ember CLI v3.20 or above
- Node.js v12 or above
See the Contributing guide for details.
This project is licensed under the MIT License.