I'm fairly new to JS development and trying to figure out some best practices for developing and using AMD libraries. Suppose I'm developing a javascript library which depends on jquery, underscore, and whatever else. Furthermore I want to make this library an AMD module and optimize it into a big monolithic file. But the question is, how monolithic? Should it also pull in jquery and underscore so that it's completely self-contained? It seems like the pros and cons of this approach are:
Pro: it's easy to use
as an app developer using this library you can just get it and add a dependency on it, without needing to know that you need jquery, underscore, etc
no having to configure requirejs with the paths to those things
no worrying about the case where one library needs jquery 1.x while another library needs 2.x
Con: it's bloated
if the main application or another library also needs to use jquery, which seems likely, it will essentially get downloaded twice (or n times)
Anything I'm missing here? So which is the right way to do this, or is the answer "it depends", or "make versions of both"? It seems like in general you'd like to share code where possible, but it puts the onus on the consumer of libraries which have non-included dependencies, and necessitates a tool which solves the constraints to find a version of a given library which is compatible with all dependent components. Is there something out there that does something like this?
I can't think of any good reason to include a third party library (such as jQuery or Underscore) with your own library. It's rare to see this technique employed anywhere, if at all, as it restricts the consumer of your code too much.
Not only would it add bloat as you say, but what if I wanted to use Zepto or Lo Dash, or a different version of jQuery? If your library simply lists jQuery and Underscore as a dependency then I could easily map those to load alternate versions or libraries.
Users of AMD (and RequireJS) are typically very comfortable with configuring paths, maps and shims as it necessary in nearly all instances, so I wouldn't worry about that.
Keeping everything separate will also allow flexibility when it comes to optimising the JS for production. For example, I often like the build jQuery into a main module that is loaded on all pages and set other modules to exclude it.
An example of what I mean with that can be seen here:
https://github.com/simonsmith/modular-html-requirejs
I would say you should provide an unoptimized version and an optimized one. If for some reason you can't do both then just provide the unoptimized version. Why the unoptimized version?
Your code is probably not bug-free. It is easier for someone using your library to track down a bug and maybe contribute a patch if there is a 1-for-1 mapping between the original source and what they observed in their debugging environment. (I've tried source maps. They were useful but produced funky results.)
You've said it yourself: libraries like jQuery could end up being loaded n times in the final application. If you provide a way to let the developers use just your library, they can run tests to determine whether they can replace different versions of jquery with just one. (The majority of cases where a library mentions or ships a specific version of jQuery, it's just because it happened to be the version that was current when the library was made, and not because of a hard dependency.)
Provide the optimized version so that someone who just wants to try our library can do it fast.
You ask:
It seems like in general you'd like to share code where possible, but it puts the onus on the consumer of libraries which have non-included dependencies, and necessitates a tool which solves the constraints to find a version of a given library which is compatible with all dependent components. Is there something out there that does something like this?
Yes. A test suite. As a consumer of libraries, I'm unlikely to use one that does not have a substantial test suite. As a producer of software, I don't produce software without a substantial test suite. As I've said above, most often a library that depends on something like jQuery or underscore or what-have-you will list whatever version that happened to be around when the library was developed.
Related
Before diving into JavaScript I was doing a lot of Java and especially liked the concept of context dependency injection. I used Google Guice a lot.
I know that JavaScript is not statically typed. And there are modulization concepts like used by requireJs or Node.js (even did something myself).
But is it thinkable or are there already solutions to inject dependencies based on a loosely defined interface.. (hope that isn't too stupid to ask)
The closest thing I have seen to what you are asking for (I think) is Architect from tim caswell.
It allows you to register modules abilities and requirements, so you can essentially request something that can preform an action, and have Architect check all the available modules to see if any of them support such an action.
You may also want to take a look at Errai (http://www.jboss.org/errai). It brings the client and sever together using the same programming paradigm by using the GWT javascript compiler bringing CDI to the browser (they're also working on JPA in the browser as well).
I am building my own JS library;
The idea is that the library should be comprised of small, independent modules, and some slightly larger utilities, that serve mainly to iron out browser differences.
I am having trouble getting anything done, because I am not being able to decide between staying dry or being loosely coupled.
An example? Given:
A small library that takes care of generating dom elements from a template
Another one that takes care of duck-typing issues (is_function, is_array...)
And a last one that creates modal boxes. That last one needs:
some type checking
will be creating the modals using only one function from the templating library
My options for the modal box library:
Be 100% dry, and dependant on the two other libraries. But that means if you are a user wanting to download only the modal box lib, you'll have to make with the two others
Allow users to pass an object of options on initiation that would allow them to specify the functions needed; defaulting to the ones of the libraries. This is better, but in practice, it still means, in 90% cases, using the provided libraries, as creating functions with the same signature might be cumbersome. Furthermore, it adds complexity to the modal box code.
Be 100% loose, and reproduce the functions needed in my modal box library; possibly more efficient because more targeted and there is no need to check for edge cases; but: any bug will have to be fixed in two places, and my download size increases.
So I am wasting time oscillating between the two extremes, refactoring a million times and never being satisfied.
I was going for a more generic question, but then I realized it is really pertaining to JS, because of the size & performance concern as well as the widespread usage.
Is there any known pattern to follow in such cases? What's the accepted way to go about this? Any thoughts are welcome.
[edit:]
This is the only article I found that spells out my concerns. Like the article says,
DRY is important, but so are [...] low coupling and high cohesion. [...] You have to take all [principles] into account and weigh their relative value in each situation
I guess I am not able to weigh their value in this situation.
Personally, I've always taken the view that Loose Coupling refers to creating seams in your code. In classical languages, such as Java, this is achieved by creating Interfaces which hide the concrete implementation. This is a powerful concept as it allows developers to 'unpick the seams' in your application and replace the concrete implementations with mocks and test doubles (or indeed, their own implementation). As JavaScript is a dynamic language developers rely on duck-typing instead of Interfaces: as nothing is frozen, every object becomes a seam in your code and can be replaced.
In direct answer to your question I think it pays dividends to always aim to decompose and modularize your code into smaller libraries. Not only do your avoid repeating code (not a good idea for a host of reasons) but you encourage re-use by other developers who only want to re-use parts of your library.
Instead of re-inventing the wheel, why not leverage some of the more popular JavaScript libraries that are out there; for example, underscore.js is a lightweight library which provides a rich toolkit for duck-type checks and Mustache.js may well take care of your templating needs.
Many existing projects already use this approach, for example, Backbone.js depends on underscore.js and jQuery Mobile depends on jQuery. Tools such as RequireJS make it easy to list and resolve your application's javascript dependencies and can even be used to combine all the separate.js files into a single, minified resource.
I like the concept of DRY, but your right it has a couple of problems.
Your end-user-developers will need to know that they need to download the dependencies of components.
Your end-user-developers will need to know that they need to configure the dependencies (i.e. the options to pass in).
To help solve 1. your project website could customise the download on the fly, so the core code is downloaded along with optional components. Like the modernizer download page.
To help solve 2. Rather than allowing users to pass in options, use sensible defaults to detect what parts of your packages have been loaded in the browser and automatically tie them up.
This loose coupling could also give you the great advantage that could also rely on 3rd party frameworks if the user already has them installed. For example selectivizr allows you to use jquery or dojo etc etc depending on what the browser has already loaded.
Perhaps you could use requirejs to help solve dependency management. I get the impression it's not really meant for libraries to use directly, but instead the end-user-developer... but it could be a nice fit.
I realise my answer doesn't answer your question directly, but perhaps it could help balance out some of the negative points of DRY.
What would be the best way to abstract away any given JavaScript framework (jQuery, MooTools etc.), that sits on the bottom of the framework stack? Essentially, I would like to have a situation where I could swap out the library, do changes only to one layer of the framework (not to every module, for example), and the whole thing could be up and running again.
So, every module should call a framework function(s), which would then be routed to the library.
You may want to use something like the Adapter Pattern. Create your own interface, exposing the methods that you will be using in your application, and then create an adapter for each toolkit that you would like to support (jQuery, MooTools, YUI, etc). Your own interface would then route the method calls to the specific adapters.
If you were to support a new toolkit, all you'd have to do is to write a new adapter that translates methods from your own interface, to the methods of the specific toolkit.
This is something that Ext JS currently does. You can choose which adapter to use (jQuery, YUI, etc) behind the method calls of the framework. For example: Ext.getCmp() would use the jQuery.$() when using the jQuery adapter. However, it is often not a very easy one-to-one mapping.
Ext JS started its life as an extension to the Yahoo UI javascript library. At that time, Ext relied on YUI for all of its low-level cross-browser code. Now that Ext is a standalone JavaScript library, you have the choice of substituting YUI for other JavaScript libraries such as Prototype, or jQuery. The source files that map the low-level Ext API around other JavaScript libraries (or Ext's own base library) are known as adapters and they live in the source/adapter subdirectory. When you include Ext in your website you choose which adapter you want to use.
From: Ext JS Manual: Source Overview
This would be writing a library for...libraries, if you are concerned about performance at all (and why wouldn't you be?) you should go a different route altogether. Another abstraction layer on top of libraries with very different approaches (especially when you get into utilities, animations, etc.) would be very, very inefficient and time consuming.
No kidding, it'd take you less time to port your code several times even in any decent size project before building (or more importantly, maintaining) a library abstraction layer like this would.
You will have to write adapters for each toolkit/library you might want to use for your framework, pretty much like ExtJS/Sencha has done (though theirs are probably not reusable).
Start out by mapping out what methods your adapter should have, it will act as your frameworks low level API.
Next step is to write an adapter for each possible toolkit/library. Some libraries will be hard to write adapters for like YUI, since they load code dynamically. You might have to compile a single .js file with needed functionality first.
Add a new toolkit/library, write a new adapter according to your mapping.
This may have been a reasonable idea if the frameworks had equivalent functionality. Unfortunately they don't; they do different things, and they do them differently. There is cross-over between them, but your wrapper would miss out on a lot because you'd only be able to do your wrapping on stuff that was in both. You'd end up with the lowest common denominator; the worst of both worlds.
My advice is to take the time to learn both libraries - MooTools and JQuery are both very good libraries, and it's good to know them both. Even if you then only use one of them in your project, you will at least be able to make an informed choice before you start.
I've written a JavaScript application that runs off Prototype & Scriptaculous. I'm thinking of rolling it out in as an open source product & would like it to be able to run on jQuery as well — I typically use jQuery for most of my other apps, except the site this app was originally built for.
I was originally thinking about building two separate applications, but maintaining them would be time consuming. Instead I'm considering building a library abstraction layer that detects if the page is running jQuery or Prototype and then calls the appropriate methods. I'm not going to abstract the whole libraries, just the functionality applicable to my application — namely selectors, events & effect. The core of my app is under 500 lines of code, so there isn't too much I need to worry about.
So instead of calling $('id') I would call LA.$('id') (LA for Library Abstraction) which would call $('id') in prototype and $('#id') in query etc…
Does this sound sane? I can't think of any technical hurdles, although I would have expected someone to have attempted this before. I couldn't find anything similar in my searches.
I expect that if you support the libraries only partly then no one will choose to use it, as they would have to finish the support, and you may find that maintaining it will be a headache, as there will be requests to add more functionality.
If your application is so small, why not just switch to jQuery for it, and standardize on that, as MS has done.
You may run into problems with versions, as, if someone uses it, and they are using an older version of a library, and there was some API change, then they will be wanting you to add support for that library.
I believe Ext.Js does something similar. They have a concept of "adapters" which allow you to sit Ext.JS on top of any of the underlying libraries and it will just work. The key difference is that they are using a 1-to-1 model where you say which library you want to use and it joins the dots, whereas I believe you're trying to say "I don't know which one will be available but whatever one you find, go use it".
I don't think it's insane, but you might have some fun trying to work out which library to use, particularly if both are available.
Web development frameworks (Prototype, jQuery, etc.) themselves are designed to be abstractions on top of the various browsers that exist. You ask the framework to do one thing and it has the same result (ideally) regardless of the browser. So, here, you are proposing an abstraction on top of abstractions. Presumably because you want people to be able to use your tool regardless of what framework they have chosen for their site. While it sounds like an interesting idea, I would personally have to guess that it would not work out in the long run. Largely because you do not know what the future holds. Prototype used to be the number one use framework, now jQuery has surpassed it. Perhaps another one will be very popular in a year, what if you then want to support that framework? That can be a lot of conditional code that you have to add, and in addition, force being loaded into the browsers of those using your tool.
I say either pick a single framework to support and stick with it, or maintain separate libraries. Ideally, it would be really cool if you could write some sort of builder script. This would allow you to set framework rules in some list and the script would build separate scripts for each framework based on some core script and the rules list. I honestly am not sure how to best accomplish something like this but it would effectively give you that abstraction on abstraction power that you are looking for without it being visible to the end user.
I've started looking into architecturing a javascript framework.
I don't want to reinvent the wheel here, especially regarding browser quirks, and know that for that matter, I'll have to rely, at some point, on some commonly-used libraries to handle low-level concerns.
The thing is, I'm not sure how i can depend on an external library for some piece of functionality (say for example dom manipulation), without tying it to my design.
Practical examples would help make a better point, but I'm not at the design stage yet, and I'm merely trying to avoid getting started on the wrong foot.
So I'm looking for some examples, guidelines, best-practices or maybe patterns that could help in this situation.
Any insight ?
EDIT : Bit of a clarification on why I'd want to do this.
My goal is to build something resembling more of an application framework than most traditional libraries like jQuery.
Think layered architecture, where the libraries would fit into the infrastructure layer (as per Evans' definition in Domain Driven Design), and handle things such as events, dom traversing and manipulation etc...
This is a very broad question, but if I were you, I would use jQuery as a base. It is a very easy library to extend and add functionality too.
I'd recommend grabbing a copy of ExtJS and taking a look at how they provide support for replacing the underlying core of their product. You can use their higher level libraries, such as grids, trees, etc, but choose to use YUI or prototype in place of their Ext core.
That should give you a good starting point.
Edit to answer comment:
Once you've downloaded ExtJS, take a look in the "adapter" folder. In there, you'll see the various adapters that exist to make ExtJS work with other libraries. You'll quickly see how they define functions that in turn make use of the appropriate underlying lib.
Segregate your code:
use the external libraries to the fullest possible, within their separate section of code.
Taking jQuery as an example, just designate a section for interfacing with jQuery and then use jQuery within that section of the library like there's no tomorrow, and give it interface functions that the rest of the code uses exclusively.
Frankly, if you integrate a library with your code and try to make it generic enough that you can trivially swap it out with something else, you're probably going to neuter the library to the point where you might as well have not included it at all.
Accept that you may need to rewrite if you end up swapping libraries, but prepare for that by giving the library-interfacing code it's own separate section, and you'll be able to write less generic, more powerful code with those external libraries and save yourself a lot of work.
This doesn't answer your pattern question, but a word about the frameworks. All of the modern JavaScript libraries are pretty good at playing well with each other, but some are better than others. Just make sure that they libraries don't monkey-patch the core objects with arbitrary properties or muck with the global namespace and you should be good to go. JQuery and YUI are both well designed and namespaced libraries. Dojo is also quite good, but a couple years ago when looking at all of the options, it seemed like Dojo encouraged the use of proprietary element attributes in markup as JS hooks. At that time Prototype was the library that mucked with objects like String/Array and didn't play well with others. I haven't looked/used Dojo or Prototype so take that with a grain of salt. I'm actively using YUI and JQuery in the same app; YUI for widgets and event management and JQuery for Selector/DOM manipulation.
I'd suggest you pick a single general purpose library or no library at all, depending on the requirements of the framework you plan to write. It's very difficult to make any kind of recommendation without more information, such as what your framework is aiming to achieve, who will be using it and in what kind of environment.
If you're considering writing a script of reasonable complexity then I would suggest learning the relevant "low level" DOM manipulation techniques for yourself. It's not as difficult as devotees of some of the famous general purpose libraries would have you believe.
Use some kind of interface to link to the library.
Don't do:
$("blah").something();
do
something("blah")
function something(id){
$(id).something();
}
Since you could call something() 20 times, it'll be simpler to update if the actual use of the library is in only 1 place.
It'll add development time and then complexity, but you won't be as dependent on a library.
I don't think this can be achieved very effortlessly. If you really want this behavior, I think you'd have to manually map the features that are covered by all libraries you want to include support for.
So that the implementation would look like:
yourLibrary.coreFramework = 'prototype';
yourLibrary.doStuff();
And your librar would treat it in the following manner:
function doStuff() {
var elem = getElement('id');
// do stuff with 'elem';
}
function getElement(id) {
switch(this.coreFramework) {
case 'prototype': return $(id);
case 'jquery': return $('#'+id);
/* etc */
}
}
Check out the jQuery or prototype frameworks.
If you decide you need to, then extend these.