Internal (private) types in definition file

Bugs
1

I was told to create issues on the forum first, before on GitHub. Therefore here the possible bug question:

Is it intended to have the underscored internal types available in definition file? See screenshot below.

screenshot
screenshot1784×583 71.5 KB

Why not using access modifier private and protected? Or configure the types exporter to ignore types with doc comments including internal tag. I’m just asking because my autocomplete (IntelliSense suggestions) is flooded with these internal types.

In JavaScript you can access all properties (including the private ones from TypeScript). The only difference here, is that you have the definition types. I just wondering is this intended or a bug?

@babylonjs/core: 7.2.1

1 Like
2

Cc @RaananW

3

Not intended, I’ll fix that :+1:

EDIT - working on that. it proves a bit of an interesting challenge, as our packages are using the internal types, but i will find a solution for that. I wonder - if you set stripInternal to true, do you still see the internal parameters?

5

I don’t know, stripInternal is for compiler, or not? Means, that is what the babylon.js repo must set, or not? I have never used this. In general use the private modifier for internal stuff. This will not be a part of the exported definition types. I think the internal tag is only for special cases, where private is not possible. But not sure how consistent babylone.js is written. There are other typescript issues too. This is maybe a breaking change. idk. I was just wondering why all the internal types were accessible to me. In IntelliSense I first have to scroll far down to see the things that are relevant to me.

6

We use internals between our different packages. loaders, for example, uses internal functionality from core. This is why they are not private. public internals are functions that we can’t (and don’t) guarantee their back-compat. There is a reasoning behind keeping the internals in our monorepo, but I am trying to see if I can make sure that they are not present in the final public packages. I have an open PR already, but I need to take care of one inheritance issue (that will probably grow to be a bit more than an inheritance issue)

7

Sorry, wanted to follow-up on this one. We can’t easily remove internals from our type definitions. I tried making a few adjustments, but eventually figured out that we have other internal projects using these internal variables, projects that will fail if I remove them all. I am going to mark that as an internal task of ours - to make sure internals are only used inside a specific class. For for now - we don’t have a proper solution for this.

9

Not quite the same thing, but maybe for BJS 10, putting a # in front of a class member #funcOrProperty will generate a private that is actually enforced at run time. The overhead seems un-noticable, especially outside the render loop.

10

Sure, we can consider that. There was the consideration of performance (I remember reading that # private are slower than typescript private, at least when targeting a lower es level). We’ll need to check that.

11

  1. I don’t agree with applying strip internal to babylonjs dts. Some classes often perform better by calling specific internal functions than by calling public functions. Some users may prefer this higher performance in exchange for the lack of guaranteed backwards compatibility.

    Also, third-party libraries that extend babylon.js at the engine level need access to internal members.

    In addition, functions specified as internal can also be interpreted as public APIs, which can break backward compatibility at any time, since they are not officially available APIs. This makes babylon js’s API flexible, but also provides a lower level of usability for the engine user

  2. I don’t think private members using # in js is a good idea either. Private members should be accessible in any non-normal way (like as any) so that users have more options for implementing the functionality they need. This is also a use case that can often be used in libraries that extend the functionality of the engine

2 Likes
12

Very important note about this - internal functions are not backwards compatible. They are public, but we might change them or their signature.

JS developers got used to being able to access everything from anywhere. Yes, it can be helpful in some ways (especially when you are just trying to patch something), but thinking of OOP and best practices, this is a big no-no. private is private, and for a reason. The engine should provide the options to extend it and to make changes to specific functionality without the need to hack something. Having said that, a class prototype has access to #functions and #members as well, so technically, there is a way around it :slight_smile:

Anyhow - this was not discussed internally, it’s just an interesting suggestion. Will be happy to get more opinions on that.