Typescript member accessability for members only used by the custom element?

Best Practices
1

When starting out with building Aurelia custom elements (using typescript) I decided to declare members only used by the custom element as private, even if they are also used in the html template. This makes them hidden if someone decides to make a view-model.ref on the element and access the custom element class through code, but since “private” doesn’t really exist in javascript, the html template can still access them.

Now my IDE of choice, Visual Studio 2017, has gotten more clever with typescript classes and started doing this for these private members as they are only read in the html template;
image

So my instinct is to now remove private on these members so that the IDE wont confuse myself and my colleagues. But then it will exposed if someone interacts with the element through code as described above, which could cause unexpected usage of the custom element.

What are your thoughts on this?

2

I used to mark them private as well. But then i changed all to public and decorated with @internal since it best describes the intention, at least for me. Also internal will make the typing disappear if you are building a library

1 Like
3

Interesting. Where can I read more about the @internal decorator? From where do I import it? (Google fails me…)

4

Oh its just a comment. You decorate the class member with multiline comment block and add @internal at the start of it

5

I see. It doesn’t seem to work in Visual Studio, I still get intellisense for that member.

I am somewhat familiar with JSDoc (http://usejsdoc.org/) but @internal is not listed there. What standard does @internal come from?

6

Yes, its only for communication, which means consumer of the class will be signaled that its not available for use outside of the class. Theoretically, they are not private, making them as such could cause confusion down the road

7

OK. Sorry, but I think I misunderstood this. How do you mean the “typing disappears”?

8

for:

class Abc {
  private d(): void {
  }
}

will generate .d.ts as:

class Abc {
  private d(): void;
}

for:

class Abc {
  /*@internal */
  d(): void {
  }
}

will generate .d.ts as:

class Abc {
  
}

So what I’ve been describing about my choice is to make things look like they way they actually are. With optional comment as a signal for reader of the class members. In stead of trying to make theoretically-public members private. The @internal comment servers 2 purposes: for app, it signals that the public member is a semi private member, shouldn’t be used directly outside of the class. For lib, it will be stripped from generated .d.ts, thus user of the lib will not see it, yielding similar effect to private.

9

Ok, got it. Thanks for your input. Using some comment like that seems like the way to go.

Considering that @internal then is some part of the spec of generation of *.d.ts files it shouldn’t be too far-fetched to suggest to IDEs that it should also affect intellisense.

(In my case I’m not building a lib, the custom elements are directly used within the same app/code base.)