@ember-decorators/argument NPM

@ember-decorators/argument

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.

Usage

import Component from '@ember/component';
import { argument } from '@ember-decorators/argument';

export default class ExampleComponent extends Component {
  @argument('string')
  arg = 'default';
}

{{example-component arg="value"}}

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.

Defining Types

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 types
oneOf : Produces a type that literally matches one of the given strings
optional: Produces an optional / nullable type that, in addition to the type that was passed in, also allows null and undefined.
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 for Function, to be used when passing a "closure action" into a component
ClassicAction - Union of string and Function, to be used if your component uses sendAction to invoke a "classic action"
Element - Fastboot safe type alias for window.Element
Node - Fastboot safe type alias for window.Node

These types can also be imported from @ember-decorators/argument/types

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

`enableCodeStripping`

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.

Example

// 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();
};

Ember Compatibility

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.