Question on project structure about tonal HOT 7 CLOSED

Yes, this the big question I'm trying to solve (and suggestions welcomed). In the previous iteration all the modules were exposed in the tonal npm package. But this approach has some problems, like the one you're showing here: it's no easy to know what's inside and how to access. Also, the package size is quite big for a library that (I think) is focused mostly for browsers.

My preference for this iteration is expose only the following packages in tonal package:

• tonal-distances (transposition, interval between notes...)
• tonal-midi (midi <=> note names conversion)
• tonal-freq (simple frequency conversion)
• tonal-arrays (work with arrays of notes and intervals)
• tonal-ranges

All the functions would be exposed without scope: tonal.transpose, tonal.range ...

That means that packages like scales, chords, keys would be necessary to import them explicitly:

var scale = require('tonal-scales')
scale.fromName('C major')

This is what I have in mind right now, but I'm open to suggestions.

I hope it helps. Cheers.

PS: both require and ES6 import would be supported.

from tonal.

Hi, just to show (instead of describe) what I'm thinking I've added a first version of the tonal package to the repo. You can take a look to the source code here: https://github.com/danigb/tonal/blob/tonal-0.50.x/packages/tonal/lib/index.js

Ideas are welcomed. Cheers.

from tonal.

Hey Dani,
I am a bit hesitant to make suggestions, because it's been a while since I have done any serious programming, and I am quite new to nodejs, npm and all the new tools and libs.

Here's what comes to mind:

If you decide to only expose a couple of the packages, isn't the criterium of which ones to select a bit subjective? I mean, I would sooner expect note, interval and chord to be included than the others, but that's just me. Another user may have different needs. It feels a bit ad hoc to me.

And if file size is the main reason for limiting the number of packages, then one could consider that (possibly) tree-shaking will become standard in the bundling tools. I know Webpack2 will have it, and Rollup has of course ... (I don't know about Browserify or jspm). But this may not be a very robust assumption right now.

The other issue is wether to export functions or entire modules. If you export functions, won't you loose the benefits of namespacing? All the method names will have to be unique across all the packages. But perhaps that is not a big problem in functional programming.
I understand your point though, it's not clear if you're importing a function or a module, and I don't know if there are conventions on this. Sometimes javascript is a bit too flexible :-)

Well, those are just a few thoughts, I hope it's useful!

from tonal.

Hi Rob,

Thanks for the detailed feedback. It's really appreciated. I try to answer (also to me) some of the concerns you arise:

If you decide to only expose a couple of the packages, isn't the criterium of which ones to select a bit subjective?

Yes, in some part is quite subjective. While I was developing tonal I keep learning new stuff from tonal music theory and wondering if I should put in the library or not. Binary scales, for example. It's not very known, but helps a lot with chord and scale detection. Or interval density to compare consonances or disonances... So, at some point I had to stop. Or I feel, at least, I have to stop growing the library (and instead add module extensions), and where to stop is subjective.

But on the other side, I found that some modules (keys, scales, chords, progressions) always require the same functionality (the one I want to include...)

And if file size is the main reason for limiting the number of packages, then one could consider that (possibly) tree-shaking will become standard in the bundling tools.

It's true that there are tools to help with file size, and thats one of the reason to move to ES6 and rollup. But currently they are all in early stages and they don't give a very pleasant user experience (learn webpack configuration is tedious, and rollup results are not always optimal by my own experience).

For me the point is to find a balance between simplicity and useful. I have to admit that I was thinking to keep scales and chords out of tonal because the file size, but probably I have to reconsider it (in fact, we are talking about a 10KB up or down... :-D)

Also, I want a source code people can understand (one of the complains of the last version), and I think that reducing the size, helps in that direction.

I even also tried to make a simple core source code that you can still read here: https://github.com/danigb/tonal/blob/tonal-0.50.x/lib/tonal.js and then extract submodules using rollup, but I abandon the idea (and the file I point to you will disappear in next release).

The other issue is wether to export functions or entire modules. If you export functions, won't you loose the benefits of namespacing?

Yes, but I feel that this constriction help me finding good function names ;-). But, of course, limit the amount functions included in the tonal package. Also I dislike the big resulting names like tonal.distance.transpose (and as far as I know is not very much in the spirit of fp)

it's not clear if you're importing a function or a module ...

My idea was to expose the full module (not only parts). And yes, my experience with functional programming is limited (in fact, this is my first attempt to write a library in a functional style) and JavaScript is too flexible ;-)

So at the end, what I like is a good user experience: you should be able to require tonal, build useful things with it without thinking in configuration or other distracting stuff, and If you need more functionality then require other extension packages (or less size, require the individual modules). To achieve this objectives I feel:

• I have to keep babel, rollup and webpack, etc... outside the user side
• Probably I have to include chords and scales
• Write documentation is my best help ;-)

May I ask... what would be a good user experience to you?

Thanks,
Dani

from tonal.

Hi Dani,

I can certainly understand your reasoning. Keeping your library light-weight and easy to set-up is indeed an important consideration.
On the subject of exporting functions or modules I am kind of undecided. I think for someone new to a library (or an app that uses a library) it is convenient to use modules so you can easily see where a function lives in case you want to check the source code or the documentation. But once you know library and are comfortable with it, I guess it is better to have direct access to a set of core functions. I think I could get used to either approach.

More in general, about my user experience, the first thing I noticed about tonal is the documentation. I think you are very right to emphasise it the way you do. As javascript developers we have to dig through dozens of libraries nowadays, and a complete and up to date documentation is really helpful. I also think it is a sign of how serious a library author is about maintaining the library in the future.
The other thing is of course the fact that you chose to make tonal a functional library. I don't have much experience with this, so I cannot really comment. I also checked Teoria, which is OO, and with my programming background it was easy for me to get it working. But with all my explorations of the last few months (I mean getting up to speed with modern frontend development) I settled on using React and Redux, which are functionally inclined.
So even though I am still in learning mode, I think i am ready to start prototyping the fretboard app I have in mind, using react/redux and tonal. I will definitely give you feedback on my experiences with tonal as I go along.

cheers,

Rob

from tonal.

Hi Rob,

Thanks a lot for your detailed feedback. It's really appreciated. I new version of tonal is coming, and I'll consider your opinions.

Good luck with your fretboard app and don't hesitate to ask if you have any problem with tonal.

Cheers,
Dani

from tonal.

Hi,

Finally for the 0.50.x release I decided to include a selection of modules in tonal facade and to not namespace. I hope is everything clear in README. Please reopen the issue if you have any question.

from tonal.