ember-arg-types


API

$3

Property decorator for declaring for glimmer component argument runtime type checks and default values, powered by facebook/prop-types.

$3

Class decorator for checking that only arguments with the @arg decorator are provided to a component (e.g. prevent misspelled or invalid arguments).

Motivation

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:

``js
@arg(string)
sortBy = 'id';
`

Instead of this:

`js
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.

`js
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;
}
`

Argument Mapping & Default Values

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'.

`js
@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.

`js
@arg
get id() {
return guidFor(this);
}
`

Type Checking

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:

`js
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;
}
`

$3

`hbs
{{! @name should be a string, not a number }}

`

!Error Example

$3

`hbs
{{! @numHeart should be @hearts }}

`

!Error Example

$3

You can find more information on prop-type validators here: Prop Type Usage Docs

$3

If an argument value fails a validation check, an Error will be thrown (in non-prod environments) by default. To disable throwing Errors , update your config/environment.js with the following:

`js
'ember-arg-types': {
// Throw errors instead of logging (default is true)
throwErrors: false
}
`

Production

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.

Installation

`
ember install ember-arg-types
`

Usage

$3

`js
// 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;
}
`

`hbs
{{! components/character.hbs }}

{{! args are mapped to local properties, thus we use this. instead of @ }}


`hbs
@name='link'
@title='hero of time'
@level={{2}}
@onClick={{this.onClick}}
@heart={{5}}
{{! Should be '@hearts' will catch because of @forbidExtraArgs }}
/>
``

Compatibility

- Ember.js v3.24 or above
- Ember CLI v3.24 or above
- Node.js v14 or above
- ember-auto-import v2

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.