Use typescript to refactor the project?

FishOrBear commented 5 years ago

I think it can be good.

z3dev commented 5 years ago

@FishOrBear Sorry but we feel that typescript isn’t necessary. Other users have added typing in various ways, so please search around for the discussions.

FishOrBear commented 5 years ago

@FishOrBear Sorry but we feel that typescript isn’t necessary. Other users have added typing in various ways, so please search around for the discussions.

Using Typescript can use the latest features, and can be compiled into other versions of js, and can bring type validation, I think it is better in refactoring projects.

Can you use the hump nomenclature?

Irrelon commented 5 years ago

@FishOrBear TypeScript is essentially a pointless language. All the features of TypeScript already exist in the JS ecosystem utilising IDE features and JSDoc. Indeed TypeScript ALSO uses JSDoc because many IDEs already supported intellisense for JSDoc comments even if they didn't or still don't natively support TypeScript.

You can have runtime type validation and compile-time type validation all via JSDoc and pure JavaScript. There is literally no need to go adding loads of extra dirt all over the code and then requiring developers to learn a new superset of the language they already know, to do what they already can, without having to transpile anything to anything else.

I'm not affiliated with jscad or this project but wanted to chip in on this. I see TS banded around all over the place as a good thing as if it solves some long standing problem we've all been suffering from. The reality is that we've had the tools and IDE support for type safety as and when we want it for quite some time in pure JS without the horrible transpilation and inevitable source mapping nonsense.

What sounds like a better approach to you:

1) Use existing language tools such as doc comments and allow devs to specify types using very well-known patterns like JSDoc

2) Force everyone who might want to participate / contribute / use your open-source project to learn a different language and install all the extra dependencies in order to compile it, purchase or download different IDEs that support this different language etc etc etc.

Ranting aside, developers are users too, and user experience matters. Pure JavaScript is easier to read, write, learn, modify and deploy. TypeScript is a solution to a problem that doesn't exist.

z3dev commented 5 years ago

In addition, all code will have camelCase variable names, which is enforced by our lint rules. Please see the V2 branch.

DanielMazurkiewicz commented 4 years ago

Guys, Typescript itself isn't maybe worth effort, but have you considered an assemblyscript? https://docs.assemblyscript.org

simonihmig commented 4 years ago

I have recently used this library in a TS project, and tbh it was a bit of a PITA. Please don't take this as an offense, to the contrary I just want to point out how the use of TS could make things better, and also be pretty well aligned with the awesome stuff you plan for v2.

But first the problems I encountered:

the API docs seem to be not up to date. E.g. all the extrusion functions seem to be missing
used @types/openjscad to get proper typings and IDE support (essentially replacing docs), but that package seems to be incomplete/out-of-date. Which is an inherent problem of ambient declarations, if they are not properly maintained and kept in sync.

I am not really able to follow the arguments of @Irrelon regarding using JSDoc as a replacement for TS.

for me I never got IDE support for types just from JSDoc comments, that comes even remotely close to TS. Neither when working in the project itself, probably even less when being an external consumer of the package.
I don't see that this project is able to enforce type safety based on that, e.g. no linting in place that could do what TS offers.
I don't believe JSDoc can even closely express what TS can. Just one example (and please correct me if I am wrong here), given this line: https://github.com/jscad/csg.js/blob/3efde2dbd9b9ded3f8fccfebe379a1d737959101/src/api/primitives/ellipse.js#L9
- will it accept undefined, or null, or both?
- it says center must be a Vec2, but in fact also accepts an array
- you cannot restrict the shape of that array, i.e. that it should have a length of 2 and only consist of numbers
- all of that you can easily express with TS: options: { center?: Vec2 | [number, number]; }

TypeScript is a solution to a problem that doesn't exist.

This seems like a pretty radical (and IMHO wrong) take. Certainly does not explain why so many (smaller but also large-scale) projects in the JS ecosystem use TS (trending upwards).

So my tl;dr:

Pros: a) better code through type safety b) higher productivity in the long term through IDE support c) generate API docs through type declarations (which cannot go out of sync with the code you write, unlike JSDoc) d) use latest ES features being (optionally) compiled down to ES5 (IE11 support anyone?) e) perfect TS typings for external consumers without additional effort

Cons: A) requires a build step B) difficulty for contributors not knowing TS

A) seems to be a requirement anyway if you want to do d). And B) seems to be mainly a concern for the existing core contributors, as this project does not seem to have this many "random" contributors.

Just my 2 cents here... keep up the good work!

DanielJoyce commented 4 years ago

Yeah, JSDOC pales in comparison to what TS can express.

Irrelon commented 4 years ago

@simonihmig Not to harp on, but what you said isn't strictly true, and goes to answering your last point about why TS adoption is seeing an uptick - primarily (IMHO) because people coming new to JS from other languages (primarily C# in my experience) don't know that something else already exists that does almost everything you need, or can see an immediate kinship between what they already know and TS, or both.

Coming originally from Spectrum Basic (aged 7), BBC Basic (aged 7), Borland C++ (aged 9), then Assembly (aged 10) and then Pascal (aged 12), Visual Basic (aged 16), JavaScript (aged 17), C# (in 2005) and finally Objective-C on the first iPhone app store, and having actually commercially shipped applications in C++, Visual Basic, C#, Objective-C and JavaScript (and have quite a few GitHub stars on projects I have single-handedly created), I feel I have a fairly good overview of the ways that languages have evolved over the years and the benefits and drawbacks of both strong-typed and weak-typed languages... (and yes, this paragraph also serves to show I'm probably considered "old" at 39 years of age now - and looking at your github photo I assume you are in a similar age range :p )...

Anyway, to your points:

you cannot restrict the shape of that array, i.e. that it should have a length of 2 and only consist of numbers

Actually you sort-of answered your own question when you provided the TS code... here is the JSDoc update that would solve the ellipse function issue:

// Contrived Shape2, Vec2, defaultResolution2D and final function for brevity, but you get the point I'm sure...
/**
 * @typedef {Object} Shape2
 */

/**
 * @typedef {Object} Vec2
 */

/**
 * @typedef {Number} defaultResolution2D
 */

/**
 *
 * @param {Object} [options] Options for construction
 * @param {Vec2|Array<number,number>} [options.center=[0,0]] Center of ellipse
 * @param {Vec2|Array<number,number>} [options.radius=[1,1]] Radius of ellipse, width and height
 * @param {Number} [options.resolution=defaultResolution2D] - number of sides per 360 rotation
 * @returns {Shape2} new Shape2 object
 */
const func = (options) => {
    return {};
};

The only change to the existing doc would be to add an or operator and Array<number,number> to describe a limited length, two-number array as a secondary acceptable type.

Here is the IDE type intellisense for that JSDoc:

You are correct that you cannot currently limit the array length when calling that function. For instance if you wrote:

func({"center": [0, 1, 2]});

The IDE would not complain. There are open tickets for fixing this in jsdoc and closure so it will likely land soon. If I were very concerned about this in a project (for instance when describing matrices where incorrect array length would break an operation as compared to the ellipse function we are discussing where a third entry in the array is ignored completely) I would actually utilise TypeScript as a linting tool (no compile horror and all the benefits we like, see https://www.hackernoon.com/why-i-no-longer-use-typescript-with-react-and-why-you-shouldnt-either-e744d27452b4).

The pros you list regarding TS are all pros for JSDoc as well, let me clarify:

a) better code through type safety

Agreed, type safety usually produces better code, but the idea that type safety only exists with TS is incorrect. A properly setup linting and pre-commit hook in git solves almost all the type safety issues without doing a compile step or installing extra modules. Have you seen how long it takes TypeScript to compile a large Ember or React project?

b) higher productivity in the long term through IDE support

I'm not sure I agree that TS makes you more productive long term vs any other way. Also given your age and industry experience you know as well as I do that things like TS come and go (like jQuery, Angular, React, Ember, JSDoc etc) - ultimately these are all attempts to tame complex problems, just like TS. My point is that the one constant is that JS is the final output regardless of the tool being utilised. This means TS is not going to be the future. Something else will take its place and get hyped up and force a bunch of people to re-train to a new thing, only for that to be replaced a couple of years down the line as well.

In my opinion and relatively extensive experience, it would be far better to be an expert in the thing that all these tools compile to, rather than adopting a new tool every couple of years.

I can (and have - see irrelon/SyncScript) write my own language extension and do what TS does now but how many devs writing TS could say the same? Understanding how TS compiles to JS or how Babel takes ES6 and compiles to ES5... these fundamentals are not learned nowadays or if they are, it is by the very very very few that want to deeply understand something.

I feel we spend too much time dumbing down important deep level understanding of a base language and that is what ultimately causes poor development output, bugs, sub-optimal code etc... and trust me, a bad developer can write bad code in any language including TS. It might be more difficult for them to do so in TS but I'd wonder why they were on the project in the first place and didn't understand the basic principles of coding first, before using tools like TS to make their lives easier.

The more we dumb down a language the fewer people understand how to write the language properly. (I call TS dumbing down by the way - and I'm aware this is a large point of contention!!). Of course we end up with "incidentally" greater numbers of devs who can write TS reasonably well and make fewer mistakes when writing it, but then all those devs will have redundant learning when TS is replaced with something else. I'd rather they learn how to write JS properly since it is a constant.

Wow... sorry for the crazy long brain dump... and that was just one point... I'll try to be brief in the next few!!!!

c) generate API docs through type declarations (which cannot go out of sync with the code you write, unlike JSDoc)

JSDoc actually creates better documentation because it encourages (and you can enforce) function descriptions, parameter descriptions etc instead of just types. See here for an example of documentation that is output entirely AUTOMATICALLY from the JSDoc comments in source code. I didn't have to write a single piece of HTML and every time I made a change to the source code I could generate new API docs automatically from it :p https://www.isogenicengine.com/docs-reference.html

If you have proper linting enabled, you cannot have it go out of sync either. As soon as you change a function call that uses the JSDoc commented function, the linting will throw an error - immediately indicating either your call is wrong or your declaration is wrong.

Since all your unit tests will be calling those functions, the unit test code will be the first point of failure which is even better since that is what unit tests are for!

d) use latest ES features being (optionally) compiled down to ES5 (IE11 support anyone?)

Babel.

e) perfect TS typings for external consumers without additional effort

Well... erm... that just sounds like an ecosystem justification and points to an annoying issue with TS which we both know exists and is why we're actually having this discussion on the openjscad repo... if you don't use TS, other TS users can suffer a degraded experience.

Really sorry for the crazy long response but this is a very interesting topic that is IMHO worth discussing at length and while I argue passionately for my "side" of the debate, I am a scientist at heart and reserve the right to change my mind or have it changed at a moment's notice 👍

Irrelon commented 4 years ago

@DanielJoyce

Yeah, JSDOC pales in comparison to what TS can express.

Can you provide an example?

hrgdavor commented 4 years ago

Dear Rob,

I am also old :D, 40. I share your views on JS vs TS.

I code in Java on daily basis as well in JS, and love bothe for what they bring.

I love crazy scripting thing in JS but would like to dobparts in a strict way.

Since you seem to have a pretty sweet setup that has strong typing support and intelisense working, I would ask if you could give few pointers.

I have tried (obviously not hard enough) and failed to get a good setup for strong typing and intelisense working.

Davor Hrg

On Fri, 3 Apr 2020, 13:15 Rob Evans, notifications@github.com wrote:

@simonihmig https://github.com/simonihmig Not to harp on, but what you said isn't strictly true, and goes to answering your last point about why TS adoption is seeing an uptick - primarily (IMHO) because people coming new to JS from other languages (primarily C# in my experience) don't know that something else already exists that does almost everything you need, or can see an immediate kinship between what they already know and TS, or both.

Coming originally from Spectrum Basic (aged 7), BBC Basic (aged 7), Borland C++ (aged 9), then Assembly (aged 10) and then Pascal (aged 12), Visual Basic (aged 16), JavaScript (aged 17), C# (in 2005) and finally Objective-C on the first iPhone app store, and having actually commercially shipped applications in C++, Visual Basic, C#, Objective-C and JavaScript (and have quite a few GitHub stars on projects I have single-handedly created), I feel I have a fairly good overview of the ways that languages have evolved over the years and the benefits and drawbacks of both strong-typed and weak-typed languages... (and yes, this paragraph also serves to show I'm probably considered "old" at 39 years of age now - and looking at your github photo I assume you are in a similar age range :p )...

Anyway, to your points:

you cannot restrict the shape of that array, i.e. that it should have a length of 2 and only consist of numbers

Actually you sort-of answered your own question when you provided the TS code... here is the JSDoc update that would solve the ellipse function issue:

// Contrived Shape2, Vec2, defaultResolution2D and final function for brevity, but you get the point I'm sure... /**

@typedef {Object} Shape2 */

/**

@typedef {Object} Vec2 */

/**

@typedef {Number} defaultResolution2D */

/*

@param {Object} [options] Options for construction

@param {Vec2|Array<number,number>} [options.center=[0,0]] Center of ellipse

@param {Vec2|Array<number,number>} [options.radius=[1,1]] Radius of ellipse, width and height

@param {Number} [options.resolution=defaultResolution2D] - number of sides per 360 rotation

@returns {Shape2} new Shape2 object */ const func = (options) => {

return {};

};

The only change to the existing doc would be to add an or operator and Array<number,number> to describe a limited length, two-number array as a secondary acceptable type.

Here is the IDE type intellisense for that JSDoc:

[image: image] https://user-images.githubusercontent.com/492293/78351241-65b71000-759e-11ea-876b-4044de851eb8.png

You are correct that you cannot currently limit the array length when calling that function. For instance if you wrote:

func({"center": [0, 1, 2]});

The IDE would not complain. There are open tickets for fixing this in jsdoc and closure so it will likely land soon. If I were very concerned about this in a project (for instance when describing matrices where incorrect array length would break an operation as compared to the ellipse function we are discussing where a third entry in the array is ignored completely) I would actually utilise TypeScript as a linting tool (no compile horror and all the benefits we like, see https://www.hackernoon.com/why-i-no-longer-use-typescript-with-react-and-why-you-shouldnt-either-e744d27452b4 ).

The pros you list regarding TS are all pros for JSDoc as well, let me clarify:

a) better code through type safety Agreed, type safety usually produces better code, but the idea that type safety only exists with TS is incorrect. A properly setup linting and pre-commit hook in git solves almost all the type safety issues without doing a compile step or installing extra modules. Have you seen how long it takes TypeScript to compile a large Ember or React project?

b) higher productivity in the long term through IDE support I'm not sure I agree that TS makes you more productive long term vs any other way. Also given your age and industry experience you know as well as I do that things like TS come and go (like jQuery, Angular, React, Ember, JSDoc etc) - ultimately these are all attempts to tame complex problems, just like TS. My point is that the one constant is that JS is the final output regardless of the tool being utilised. This means TS is not going to be the future. Something else will take its place and get hyped up and force a bunch of people to re-train to a new thing, only for that to be replaced a couple of years down the line as well.

In my opinion and relatively extensive experience, it would be far better to be an expert in the thing that all these tools compile to, rather than adopting a new tool every couple of years.

I can (and have - see irrelon/SyncScript) write my own language extension and do what TS does now but how many devs writing TS could say the same? Understanding how TS compiles to JS or how Babel takes ES6 and compiles to ES5... these fundamentals are not learned nowadays or if they are, it is by the very very very few that want to deeply understand something.

I feel we spend too much time dumbing down important deep level understanding of a base language and that is what ultimately causes poor development output, bugs, sub-optimal code etc... and trust me, a bad developer can write bad code in any language including TS. It might be more difficult for them to do so in TS but I'd wonder why they were on the project in the first place and didn't understand the basic principles of coding first, before using tools like TS to make their lives easier.

The more we dumb down a language the fewer people understand how to write the language properly. (I call TS dumbing down by the way - and I'm aware this is a large point of contention!!). Of course we end up with "incidentally" greater numbers of devs who can write TS reasonably well and make fewer mistakes when writing it, but then all those devs will have redundant learning when TS is replaced with something else. I'd rather they learn how to write JS properly since it is a constant.

Wow... sorry for the crazy long brain dump... and that was just one point... I'll try to be brief in the next few!!!!

c) generate API docs through type declarations (which cannot go out of sync with the code you write, unlike JSDoc) JSDoc actually creates better documentation because it encourages (and you can enforce) function descriptions, parameter descriptions etc instead of just types. See here for an example of documentation that is output entirely AUTOMATICALLY from the JSDoc comments in source code. I didn't have to write a single piece of HTML and every time I made a change to the source code I could generate new API docs automatically from it :p https://www.isogenicengine.com/docs-reference.html

If you have proper linting enabled, you cannot have it go out of sync either. As soon as you change a function call that uses the JSDoc commented function, the linting will throw an error - immediately indicating either your call is wrong or your declaration is wrong.

Since all your unit tests will be calling those functions, the unit test code will be the first point of failure which is even better since that is what unit tests are for!

d) use latest ES features being (optionally) compiled down to ES5 (IE11 support anyone?) Babel.

e) perfect TS typings for external consumers without additional effort Well... erm... that just sounds like an ecosystem justification and points to an annoying issue with TS which we both know exists and is why we're actually having this discussion on the openjscad repo... if you don't use TS, other TS users can suffer a degraded experience.

Really sorry for the crazy long response but this is a very interesting topic that is IMHO worth discussing at length and while I argue passionately for my "side" of the debate, I am a scientist at heart and reserve the right to change my mind or have it changed at a moment's notice 👍

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/jscad/csg.js/issues/164#issuecomment-608376970, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAS5U6VPIEJ6TRBHECD3CJDRKXANDANCNFSM4HCCLDZQ .

Irrelon commented 4 years ago

@hrgdavor I would be happy to do so... it's probably best described in a blog post as I'm conscious I've probably more than outstayed my welcome on this issue thread because what we're discussing now isn't really openjscad related beyond the issue the OP opened.

I'll put together a simple how-to and post the link here for anyone interested.

z3dev commented 3 years ago

Everyone!

There's a new pull request (OpenJSCAD.org) for adding TypeScript declarations. It would be really helpful if others (you) take a look at the declarations, and if possible try them.

https://github.com/jscad/OpenJSCAD.org/pull/726

z3dev commented 3 years ago

@hrgdavor
@simonihmig @DanielJoyce @Irrelon

Typescript declarations have been integrated into V2 JSCAD, as part of the ‘modeling’ package of OpenJSCAD.org. Please use that, and raise any new issues as part of OpenJSCAD.org

hrgdavor commented 3 years ago

TLDR; I don't use Typescript and it is not likely to happen soon. But thanks for the mention :)

Typescript sounds ok to me, and I fully understand the benefits as I code as much in Javascript as in Java... but still have not found a satisfactory setup where I would combine javascript and Typescript.

Facebook flow was closest I got, but disappointing in the end (an important deal-breaking issue they ignored for 4+ years and will never likely fix)

z3dev commented 3 years ago

Done in V2. See OpenJSCAD.org, package 'modeling'

jscad / csg.js

Use typescript to refactor the project? #164