Skip to content

Commit 70dce07

Browse files
ssutarpzuraq
ssutar
authored and
pzuraq
committed
Add usage documentation including details about all the options (#44)
1 parent 97c81ca commit 70dce07

File tree

1 file changed

+141
-16
lines changed

1 file changed

+141
-16
lines changed

‎README.md

Lines changed: 141 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,165 @@
33
[![Build Status](https://travis-ci.org/scalvert/ember-es6-class-codemod.svg?branch=master)](https://travis-ci.org/scalvert/ember-es6-class-codemod)
44
[![npm version](https://badge.fury.io/js/ember-es6-class-codemod.svg)](https://badge.fury.io/js/ember-es6-class-codemod)
55

6-
A collection of codemod's for ember-es6-class-codemod.
6+
Codemods for transforming ember app code to native ES6 class syntax with decorators
7+
8+
## Installation
9+
10+
```
11+
yarn global add ember-es6-class-codemod
12+
```
713

814
## Usage
915

10-
To run a specific codemod from this project, you would run the following:
16+
The Ember ES6 codemods can be run using the following command
1117

1218
```
13-
npx ember-es6-class-codemod <TRANSFORM NAME> path/of/files/ or/some**/*glob.js
19+
ember-es6-class-codemod ember-object [OPTIONS] path/of/files/ or/some**/*glob.js
20+
```
1421

15-
# or
22+
The codemods accept the following options:
1623

17-
yarn global add ember-es6-class-codemod
18-
ember-es6-class-codemod <TRANSFORM NAME> path/of/files/ or/some**/*glob.js
24+
| Option | Value | Default | Details |
25+
| --------------------- | --------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
26+
| --class-fields | boolean | true | Enable/disable transformation using class fields |
27+
| --decorators | boolean | false | Enable/disable transformation using decorators |
28+
| --type | String | Empty (match all types in path) | Apply transformation to only passed type. The type can be one of `services`, `routes`, `components`, `controllers` |
29+
| --runtime-config-path | File path | Empty | Transformation using runtime configuration from the path |
30+
31+
### Class Fields
32+
33+
Class fields are currently defined as a [stage 3 proposal](https://github.com/tc39/proposal-class-fields) in the [ECMA TC39 process](https://tc39.github.io/process-document/). As such, they are added as a configurable option in the transforms, enabled by default. If set to **false**, it will NOT transform the object properties to class fields but instead error out.
34+
35+
For example, the below declaration
36+
37+
```
38+
const Foo = EmberObject.extend({
39+
prop: "defaultValue",
40+
});
1941
```
2042

21-
## Transforms
43+
Will be transformed to
44+
45+
```
46+
class Foo extends EmberObject {
47+
prop = "defaultValue";
48+
}
49+
```
50+
51+
### Decorators
52+
53+
Decorators are currently a [stage 2 proposal](https://github.com/tc39/proposal-decorators) in the [ECMA TC39 process](https://tc39.github.io/process-document/). They are added as a configurable option in the transforms. If set to true, it will transform the object's properties to decorators wherever required.
54+
55+
For example, the below declaration
56+
57+
```
58+
import { inject as service } from "@ember/service";
59+
const Foo = EmberObject.extend({
60+
b: service("store"),
61+
});
62+
```
63+
64+
Will be transformed to
65+
66+
```
67+
import { service } from "@ember-decorators/service";
68+
class Foo extends EmberObject {
69+
@service("store")
70+
b;
71+
}
72+
```
73+
74+
**Note** The decorators support is not built in inside Ember. Decorators support requires the use of the [ember-decorators](https://github.com/ember-decorators/ember-decorators) addon and should be added as dependency to your application. The codemod takes care of importing required decorators from the `ember-decorators` addon.
75+
76+
### Types
77+
78+
The option `type` can be used to further target transforms to a particular type of ember object within the application or addon. The types can be any of the following:
79+
80+
| Type | Option |
81+
| ----------- | ------------------ |
82+
| Services | --type=services |
83+
| Routes | --type=routes |
84+
| Components | --type=components |
85+
| Controllers | --type=controllers |
86+
87+
The path of the file being transformed is matched against the glob pattern of the type to determine whether to run the specific transforms.
88+
89+
If a type is not provided, the codemods will run against all the **_types_** in the path provided.
90+
91+
### Runtime Config Path
92+
93+
As per conventional codemods, the code is converted from one API to another by statically analyzing patterns within it. While this works well most of the time, there are cases that can only be analyzed at runtime to determine the full shape of the code to transform. For example, if we need to determine the class hierarchy, it is not possible with static analysis to determine the parent classes and their properties.
94+
95+
The codemods are designed with `runtime data` as input to correctly transform the code. For each file currently being transformed, the codemods need a `configuration file`, which will provide additional metadata about the properties of the ember object.
96+
97+
The runtime config path must point to a JSON file containing runtime data of the format:
98+
99+
```
100+
{
101+
data: [{
102+
"/absolute/file/path": {
103+
"computedProperties": ['computedProp1', ...],
104+
"observedProperties": ['observedProp1', ...],
105+
"observerProperties": {
106+
"observerProp1": ["prop1", "prop2", ...]
107+
},
108+
"offProperties": {
109+
"offProp": ["prop3", ...]
110+
},
111+
"overriddenActions": ["overriddenAction1", ...],
112+
"overriddenProperties": ["overriddenProp1"],
113+
"ownProperties": ["prop1", ...],
114+
"type": "Component|Route|Controller|EmberObject",
115+
"unobservedProperties": {
116+
"unobservedProp1": ["prop1", ...]
117+
}
118+
}
119+
}]
120+
}
121+
```
122+
123+
_How to get this runtime data from an ember application_
124+
125+
There are tools available which provide various ways of extracting runtime data. The following are examples:
126+
127+
- [Dyfactor](https://github.com/dyfactor/dyfactor)
128+
- [code-to-json](https://github.com/mike-north/code-to-json)
129+
130+
A [dyfactor plugin](https://github.com/ssutar/ember-es6-class-codemod-dyfactor) has been developed to extract runtime data from an ember application. However any tool which provide the runtime data with the expected format can be used with these codemods.
131+
132+
## Debugging
133+
134+
The codemods log execution information in the `codemods.log` file in the current directory from where the codemods are being executed. Specifically, details such as failures and reasons for failures, are logged. This would be the recommended starting point for debugging issues related to these codemods.
135+
136+
## Unsupported Types
137+
138+
While the codemods transforms all types of ember objects, it does not support transformation of
139+
140+
- `ember-data` entities for example `DS.Model`, `DS.Adapter` etc
141+
- Mixins
142+
- Ember Object having a property with `ObjectExpression` as value (`actions` and `queryParams` are exception) See `eslint-plugin-ember/avoid-leaking-state-in-ember-objects` for more details.
143+
- Ember object having property with `meta` or `property` modifiers
144+
145+
## More Transform Examples
22146

23147
<!--TRANSFORMS_START-->
24-
* [ember-object](transforms/ember-object/README.md)
25-
* [helpers](transforms/helpers/README.md)
26-
<!--TRANSFORMS_END-->
148+
149+
- [ember-object](transforms/ember-object/README.md)
150+
- [helpers](transforms/helpers/README.md)
151+
<!--TRANSFORMS_END-->
27152

28153
## Contributing
29154

30155
### Installation
31156

32-
* clone the repo
33-
* change into the repo directory
34-
* `yarn`
157+
- clone the repo
158+
- change into the repo directory
159+
- `yarn`
35160

36-
### Running tests
161+
### Running Tests
37162

38-
* `yarn test`
163+
- `yarn test`
39164

40165
### Update Documentation
41166

42-
* `yarn update-docs`
167+
- `yarn update-docs`

0 commit comments

Comments
 (0)