{"id":13806581,"url":"https://github.com/ember-decorators/argument","last_synced_at":"2025-05-02T22:31:18.050Z","repository":{"id":57111341,"uuid":"105836336","full_name":"ember-decorators/argument","owner":"ember-decorators","description":"Decorators for Component and Object arguments in Ember","archived":false,"fork":false,"pushed_at":"2023-12-15T02:55:48.000Z","size":357,"stargazers_count":30,"open_issues_count":20,"forks_count":18,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-26T08:53:25.814Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ember-decorators.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-05T01:13:24.000Z","updated_at":"2023-10-24T18:44:31.000Z","dependencies_parsed_at":"2024-01-09T05:01:41.103Z","dependency_job_id":"0fa71fec-c909-400d-b35d-1c4ade98dab2","html_url":"https://github.com/ember-decorators/argument","commit_stats":{"total_commits":102,"total_committers":17,"mean_commits":6.0,"dds":0.3137254901960784,"last_synced_commit":"3edf6d105f3c5b3aeaabf68361795795f1183dfc"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-decorators%2Fargument","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-decorators%2Fargument/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-decorators%2Fargument/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-decorators%2Fargument/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ember-decorators","download_url":"https://codeload.github.com/ember-decorators/argument/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252116216,"owners_count":21697336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:13.543Z","updated_at":"2025-05-02T22:31:13.036Z","avatar_url":"https://github.com/ember-decorators.png","language":"JavaScript","readme":"# @ember-decorators/argument\n\n[![Build Status](https://travis-ci.org/ember-decorators/argument.svg?branch=master)](https://travis-ci.org/ember-decorators/argument)\n![Ember Version Badge](https://badgen.net/badge/ember/v3.6.0+/orange)\n\nThis addon provides a decorator that allows you to declaratively specify component arguments. Through it, you can have run-time type checking of component usage.\n\n## Usage\n\n```js\nimport Component from '@ember/component';\nimport { argument } from '@ember-decorators/argument';\n\nexport default class ExampleComponent extends Component {\n  @argument('string')\n  arg = 'default';\n}\n```\n\n```hbs\n{{example-component arg=\"value\"}}\n```\n\nFor 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.\n\nWhen 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.\n\nIn addition, any unexpected arguments to a component will also cause an error.\n\n## Defining Types\n\nThe `@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.\n\n### Primitive Types\n\nFor 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:\n\n- `any`\n- `boolean`\n- `null`\n- `number`\n- `object`\n- `string`\n- `symbol`\n- `undefined`\n\nThere are also a number of helpers that can be used to validate against a more complex or specific type:\n\n- `arrayOf`: Produces a type for an array of specific types\n- `oneOf` : Produces a type that literally matches one of the given strings\n- `optional`: Produces an optional / nullable type that, in addition to the type that was passed in,\n  also allows `null` and `undefined`.\n- `shapeOf`: Accepts an object of key -\u003e type pairs, and checks the shape of the field to make sure it\n  matches the object passed in. The validator only checks to make sure that the fields exist and are their\n  proper types, so it is valid for all objects which fulfill the shape (structural typing)\n- `unionOf`: Produces a union type from the specified types\n\n```js\nimport Component from '@ember/component';\nimport { argument } from '@ember-decorators/argument';\nimport {\n  arrayOf,\n  oneOf,\n  optional,\n  shapeOf,\n  unionOf\n} from '@ember-decorators/argument/types';\n\nexport default class ExampleComponent extends Component {\n  @argument(arrayOf('string'))\n  stringArray;\n\n  @argument(oneOf('red', 'blue', 'yellow'))\n  primaryColor;\n\n  @argument(optional(Date))\n  optionalDate;\n\n  @argument(shapeOf({ id: 'string' }))\n  objectWithId;\n\n  @argument(unionOf('number', 'string'))\n  numberOrString;\n}\n```\n\nIn addition, this library includes several predefined types for convenience:\n\n- `Action` - Type alias for `Function`, to be used when passing a [\"closure action\"][closure-action] into a component\n- `ClassicAction` - Union of `string` and `Function`, to be used if your component uses `sendAction` to invoke a \"classic action\"\n- `Element` - Fastboot safe type alias for `window.Element`\n- `Node` - Fastboot safe type alias for `window.Node`\n\nThese types can also be imported from `@ember-decorators/argument/types`\n\n### Class Instances\n\nThe `@argument` decorator can also take a class constructor to validate that the property value is an instance of that class\n\n```js\nimport Component from '@ember/component';\nimport { argument } from '@ember-decorators/argument';\n\nclass Task {\n  constructor() {\n    this.complete = false;\n  }\n}\n\nexport default class TaskComponent extends Component {\n  @argument(Task)\n  task;\n}\n```\n\nPassing a class works with all of the type helpers mentioned above.\n\n## Installation\n\nWhile `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\n\n```bash\nember install ember-decorators\nember install @ember-decorators/argument\n```\n\n## Configuration\n\n### Run-Time\n\n#### `argumentWhitelist`\n\n**Type**: `Array` or `Object` | **Default**: `[]`\n\nOnce `@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.\n\nWhen provided an array of `string`, those exact properties will be added to the whitelist.\n\nTo provide a more flexible solution, you can also provide an object with the following structure:\n\n```javascript\nshapeOf({\n  // Whitelist any string starting with one of these values\n  startsWith: optional(arrayOf('string'))\n  // Whitelist any string ending with one of these values\n  endsWith: optional(arrayOf('string'))\n  // Whitelist any string that include one of these values anywhere\n  includes: optional(arrayOf('string'))\n  // Whitelist any string that exactly matches one of these values\n  matches: optional(arrayOf('string'))\n})\n```\n\n##### Example\n\n```javascript\n// config/environment.js\nmodule.exports = function(environment) {\n  let ENV = {\n    // ...\n    '@ember-decorators/argument': {\n      argumentWhitelist: {\n        startsWith: ['hotReloadCUSTOM']\n      }\n    }\n  };\n\n  // ...\n\n  return ENV;\n};\n```\n\n### Build-Time\n\n#### `enableCodeStripping`\n\n**Type**: `Boolean` | **Default**: `true`\n\nBy 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.\n\nHowever, if the process seems buggy or you want the validation in production, setting this flag to `false` will prevent any code from being removed.\n\n##### Example\n\n```javascript\n// ember-cli-build.js\nconst EmberApp = require('ember-cli/lib/broccoli/ember-app');\n\nmodule.exports = function(defaults) {\n  let app = new EmberApp(defaults, {\n    '@ember-decorators/argument': {\n      enableCodeStripping: false\n    }\n  });\n\n  return app.toTree();\n};\n```\n\n## Ember Compatibility\n\nThis 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][native-class-constructor-update] that landed in that Ember version.\n\nSupport can be polyfilled using [`ember-native-class-polyfill`][ember-native-class-polyfill] back to any version that it supports. Currently, that is Ember `3.4`.\n\n## Running\n\n- `ember serve`\n- Visit your app at [http://localhost:4200](http://localhost:4200).\n\n## Running Tests\n\n- `npm test`\n- `npm run test:all` (Runs `ember try:each` to test your addon against multiple Ember versions)\n- `ember test --server`\n\n## Building\n\n- `ember build`\n\nFor more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/).\n\n[native-class-constructor-update]: https://github.com/emberjs/rfcs/blob/master/text/0337-native-class-constructor-update.md\n[ember-native-class-polyfill]: https://www.npmjs.com/package/ember-native-class-polyfill\n[closure-action]: https://alexdiliberto.com/posts/ember-closure-actions/\n","funding_links":[],"categories":["Packages"],"sub_categories":["ES6"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-decorators%2Fargument","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fember-decorators%2Fargument","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-decorators%2Fargument/lists"}