Documentation for ESNext w/o typescript

[hannahhoward]

Is it correct that the NG team is not going to provide documentation for those who want to write in ESNext (i.e. ES2015) without using Typescript?

An example of where this would be useful is when you're trying to inject services in other services. The current solution seems to rely on either Typescript or parameter decorators (not in the Ecmascript decorator proposal). Given that "ES2015" was presented as a proposed platform for Angular 2 at NgConnect, it seems like there should be a clear path for those who want to use this platform. Also, when the team says "ES2015" do they mean actual ES2015 (which has no decorators at all) or ESNext... i.e. some future unknown javascript that would include decorators and perhaps even parameter decorators?

[robwormald]

In all cases I can think of, there's a non-ES-whatever syntax for anything TypeScript sugars away. At the moment we're focused on providing an ES5 documentation for those who want to use Angular without build tooling, and TypeScript as it has a defined feature set we can point to.

That's not to say we won't document such syntax (I think it's a good idea) but currently our focus is on those two (well, three, with Dart), as its hard for us to say "well, turn on feature xyz in the transpiler of your choice" (for example, the Babel 6 upgrade currently doesn't support decorators at all, proposal or not...)

For reference:

class SomeService {
  constructor(){
    console.log('helloo');
  }
}

class App {
  constructor(service){}

  static get parameters(){
    return [SomeService]
  }

  static get annotations(){
    return [new ComponentMetadata({
    selector: 'app',
    template: 'hello world',
    providers: [SomeService]})]
  }
}

//alternately
App.annotations = [
  new ComponentMetadata({
    selector: 'app',
    template: 'hello world',
    providers: [SomeService]})
];

App.parameters = [ SomeService ]

bootstrap(App);

is how you'd define a pure ES2015 setup, with no dependence on decorators.

You could, until Babel6 adds support, do your own pseudo-decorator (totally making this up as I go, warning... )

const decorateComponent = (config) => (ctor) => {
  ctor.annotations = [new ComponentMetadata(config)];
}

used like

decorateComponent({ selector: 'app', template: 'hello world' })(App);

Or use the ES5 syntax which is similar.

edit: updated with both static or attach options.

[wardbell]

If this is important to you, we could use your help with very concrete questions about how to do something in ES2015 that you can't figure out how to do in Angular 2.

We'd want to make the ES2015 road reasonable even if we don't have the resources right now to give it its own track in the documentation.

May I add on a personal note that TypeScript is awfully nice, especially when you factor in the productivity benefits from the tooling support. I (personally) don't see the benefit in straight-up-ES2015; if you're going to transpile, you might as well get some productivity back for the effort.

Again, that's ME talking, not the Angular team.

[wardbell]

FWIW, here is an additional, potentially simpler approach as it relates to marking parameters to be injected into a component.

// Typescript
class MyComponent {
 constructor(myService:MyService, @Inject("foo") foo){}
}

// Babel without parameters decorators:
class MyComponent {
 static parameters = [MyService, new Inject('foo')];
 constructor(myService, foo){}
}

Clearly such things are possible. It's a bit early to know if we have the "best" guidelines and APIs for it. All in due time, friends.

[robwormald]

I don't think the above actually works @wardbell as iirc, ES2015 doesn't have static properties as a thing (though babel does have a transformer to enable it)

[aciccarello]

In the AngularConnect team panel video @naomiblack talked about why the docs aren't in ES2015, which I think makes sense.

Do the docs have a guide for mapping TypeScript concepts to ES2015 with/without decorators? If there's a guide, users should be able to interpret the TypeScript docs well enough.

[wardbell]

@robwormald I'm pretty sure static properties are supported. I know this post is not official but Scott Allen rarely gets this kind of thing wrong.

I find the spec tough going but this link supports the notion of a static method.

Do the docs have a guide for mapping TypeScript concepts to ES2015 with/without decorators?

Not yet. We will.

[robwormald]

@wardbell static methods (including getters and setters) are ES6, static properties are not.

So:

class Foo {
  static someMethod(){ return 'baz' }
  static get bar(){ return 'baz' }
}

Foo.someMethod() //baz
Foo.bar //baz

is valid ES6, while:

class Foo {
  static bar = 'baz' 
}

is not. The only way to attach static properties (without a getter) is after the fact:

class Foo {}
Foo.bar = 'baz'

or nicely with a decorator (which brings this thread full circle!)

const staticProps = props => ctor => Object.assign(ctor, props);

@staticProps({ bar: 'baz' })
class Foo {}

Nor, for that matter, are instance properties declarable this way in ES6 :/

class Foo {
  bar = 'baz' //Uncaught SyntaxError: unknown: Unexpected token (2:6)
}

I believe this is the latest proposal to fix this in ES7 - https://github.com/jeffmo/es-class-fields-and-static-properties

+1 for Typescript here, as all of the following are valid TS

class Foo {
  //static class property
  static bar = 'baz'
  //instance class property
  baz = 'baz!'
}

Foo.bar //baz

let aFoo = new Foo();
aFoo.baz //baz!

[wardbell]

@robwormald ROFL! Don't make me lecture you on the difference between a field (unmediated data value) and a property WOOT! (access to the data via methods with compiler sauce that makes it look like a field).

Joking aside, your distinction IS clarifying.

[hannahhoward]

Hi! So sorry for posting an issue and running. In my opinion the very first thing to decide is what specific platform is Angular supporting when the team says "ES2015". To me this is ultimately the most important piece of information -- even above an beyond specific documentation.

ES5 clearly refers to a version of Angular 2 that is written entirely in the ES5 standard and runs un-transpiled in the browser. Typescript clearly means Typescript.

When the team says Angular 2 supports "ES2015", I have no idea. In the slides and talks at AngularConnect it sounds like "ES2015" means everything that's in typescript, except for types. That would cover both stuff that's in ES2015, might be in ES2016, and stuff that isn't even proposed yet.
Or it could actually refer to ES2015, the standard, which would take out decorators entirely and make defining components for example look very different, even when you include classes.

My opinion is particularly if Angular's "ES2015" means at minimum a javascript that has decorators, we should stop calling it ES2015 cause it's very confusing. Maybe the team should say ESNext, but if that's the case, the standard should really be "stuff that's at minimum got a stage 0 proposal to become part of javascript" -- or that a least one transpiler other than typescript will compile.

Or maybe the best thing is to just say Angular 2 supports ES5 and Typescript for now. And deal with supporting some other ES version in a point release. That would be much more clear. Since the types are optional in Typescript, saying Typescript is the required transpiler isn't that much of a limitation.

[orizens]

@hannahhoward
I would also like to be able to write ng2 with es 2015/next only (no typescript).
I think that we can start by converting typescript concepts in ng2 to its equivalent without typescript and rather es2015/next only.
i.e, injecting services with @Inject() rather than typing myService: MyService.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}