Pseudobry

Introduction to Data Modeling with JSData

Tue, 16 Jun 2015 00:00:00 +0000

Inspired by Ember Data, JSData is a framework-agnostic, datastore-agnostic ORM for Node.js and the Browser.

JSData’s adapters handle communication with various storage layers, such as localStorage, Firebase, RethinkDB, or your RESTful backend.

In a typical scenario, you load data into the store, which maintains a single representation of every unique record coming from your storage layer. The data store offers an API for read, update, and delete operations, which are executed in your storage layer by an adapter, with the results finally synced back to the store. This is your Data or Model layer.

The Model layer is typically where your business logic resides–where you manipulate your data. There are many variations on this pattern, and JSData can work with your preferences.

JSData runs in the browser, communicating with storage layers such as localStorage, Firebase, your RESTful backend (HTTP target), etc.

JSData also runs in NodeJS, where adapters for MongoDB, Redis, RethinkDB, MySql/Postgres/SQLite, etc. are available.

JSData presents a uniform API for executing your typical CRUD operations against any storage layer for which an adapter is available. You can easily combine adapters for more complicated data management.

It is easy to add JSData to your project. Let’s get started:

Install

<npm|bower> install --save js-data

JSData is available on cdnjs and jsDelivr.

You can add JSData to your app as a script tag, via import JSData from 'js-data', require('js-data'), define(['js-data'], ...), etc.

Create a store

The DS constructor function takes an optional options object which can be used to override the default settings for your new store. You can also create a store via JSData.createStore([options]).

Connect to storage

We’re not actually working with any storage layers yet, so let’s register an adapter.

<npm|bower> install --save js-data-firebase

js-data-firebase is available on cdnjs and jsDelivr.

You can add js-data-firebase to your app as a script tag, via import DSFirebaseAdapter from 'js-data-firebase', require('js-data-firebase'), define(['js-data', 'js-data-firebase'], ...), etc.

Model your data

You start modeling your data by registering Resources with the store:

A JSData Resource defines metadata that the store uses to interact with data of that type. The Resource object returned by DS#defineResource(options) exposes an API for working directly with data of that Resource.

With a few lines of code, we can already do all kinds of things with data of type User.

Create a user in Firebase

Update the user

Destroy the user

The tip of the iceberg

I hardly had to write an code, and I already have a fully functional CRUD API on top of Firebase! I can easily add more resources, setup relations between them, and even add another adapter for a more complex application.

You know when you show a treat to a starving (but obedient) puppy, and the puppy just starts drooling all over the floor? That puppy is you right now.

JSData will save you time. It’s the Twitter Bootstrap of data layers.

Knock yourself out:

Respect your data - An introduction to angular-data

Tue, 13 May 2014 00:00:00 +0000

A presentation of mine given at an AngularJS Utah meetup.

Data Management & Caching with Angular.js

Tue, 12 Nov 2013 00:00:00 +0000

A presentation of mine given at an AngularJS Utah meetup.

Let express.js and async.js make your life easier

Fri, 04 Oct 2013 00:00:00 +0000

Out of the box node.js provides an http module for sending and receiving HTTP requests. It attempts to abstract away the more tedious parts of forming requests and parsing responses. With the http module you can write scripts that communicate with the world via HTTP or even write simple HTTP web servers. This is great, but when it comes time to build a service api, node’s http module starts to feel like a single screwdriver when you need an entire toolbox. ExpressJS comes into the picture as a minimal and flexible web application framework for node.js. Express provides a set of tools for easily interacting with HTTP requests and responses, in addition to bringing middleware layers to your api. In addition to the fundamental features provided by Express, the highly popular async utility provides a robust tool for managing asynchronous control flow. Consider this RESTful api endpoint created using Express:

app.get('/posts/:id', function (req, res, next) {
  db.find(req.params.id, function (err, posts) {
    if (err) {
      // Pass the error on to be handled by some other middleware
      next(err);
    } else {
      res.send(200, posts);
    }
  });
});

Here, syntactic sugar lays out an endpoint that accepts GET requests. Express automatically parses parameters within the request url, and exposes them in the params object of the request.

Notice the line:

if (err) {
  next(err);
}

This is where the code checks for any errors returned by the database call. Instead of handling the error on the spot with something like:

if (err) {
  // Handle the error on the spot
  res.send(500, 'There was an error!');
}

I pass the error down the middleware chain to be handled elsewhere. Requests pass through middleware in the order that you tell Express to “use” them (see code below). This is convenient when you want to handle errors from many places with the same code. In order for this to work, previously in my application I had told Express to add a handler to the middleware chain with something like this:

// This tells express to route ALL requests through this middleware
// This middleware ends up being a "catch all" error handler
app.use(function (err, req, res, next) {
  if (err.msg) {
    res.send(500, { error: err.msg });
  } else {
    res.send(500, { error: '500 - Internal Server Error' });
  }
});

So when the request (GET “/posts/13”) comes from the client to Express, the request is passed down the middleware chain until it is handled. Most middleware don’t fully handle the request, but augment it. For example, Expresses uses middleware to parse the url parameters and attach the params object to the request object, which is then passed along to be handled by the code written to handle the “/posts/:id” route. If there’s an error, the route can handle the error, or pass it along to be handled by a middleware error handler like the one above.

Middleware is also especially useful for requiring authentication in api endpoints. For example, we will secure the “/posts/:id” route:

function restrict(req, res, next) {
  if (req.session.user) {
    // User has active authenticated session, move along
    next();
  } else {
    // Unauthenticated!
    res.send(401);
  }
}

And now to tell Express to send the request through the “restrict” middleware before letting the code for the “/posts/:id” route handle the request:

app.get('/posts/:id', restrict, function (req, res, next) {
  db.find(req.params.id, function (err, posts) {
    if (err) {
      next(err);
    } else {
      res.send(200, posts);
    }
  });
});

Using middleware, it’s possible to build a robust and highly functional service api without duplicating code.

When handling a request, and especially when that involves doing file I/O or talking to a database, it often leads what’s called “callback hell”, or deeply nested callback functions. This makes the code hard to read, as it’s hard to follow the flow of the program. Here’s an example of trying to create a new user:

function create(attrs, cb) {
  db.table('user').filter({email: attrs.email}).count().run(db.conn, function (err, count) {
    if (count > 0) {
      cb('Email already exists!');
    } else {
      db.table('user').filter({username: attrs.username}).count().run(db.conn, function (err, count) {
        if (count > 0) {
          cb('Username already exists!');
        } else {
          db.table('user').insert(attrs).run(db.conn, function (err, newUser) {
            if (err) {
              cb(err);
            } else {
              cb(null, newUser);
            }
          });
        }
      });
    }
  });
}

Imagine how painful it would be to read code nested eight or ten levels deep! Thankfully, async can help us out. Here’s the same example using async:

function create(attrs, cb) {
  async.waterfall([
    // check for duplicate email
    function (next) {
      db.table('user').filter({email: attrs.email}).count().run(db.conn, next);
    },
    // check for duplicate username
    function (count, next) {
      if (count > 0) {
        cb('Email already exists!');
      } else {
        db.table('user').filter({username: attrs.username}).count().run(db.conn, next);
      }
    },
    // Insert the new user
    function (count, next) {
      if (count > 0) {
        cb('Username already exists!');
      } else {
        db.table('user').insert(attrs, { 'return_vals': true }).run(db.conn, next);
      }
    }
  ]);
}

Now each step is listed in its logical order, at the same level of nesting. This particular function of async–waterfall–performs asynchronous operations one after another, each waiting for the previous to complete before executing, and each receiving the return arguments of the preceding function. Async automatically checks for errors and returns them, eliminating the if (err) cb(err); boilerplate code.

Using the combination of Express and async on one of my projects has been a pleasant exercise that’s resulted in a clear, concise api definition and easy to follow code. I would definitely give async a try, as it can do almost everything promises can do, without the performance overhead. async has a myriad of functions you can check out.

What is Node.js?

Wed, 18 Sep 2013 00:00:00 +0000

This post is my basic answer to the question:

What is NodeJS?

Here I briefly discuss a few things about NodeJS that I think are essential to understanding what NodeJS is as a programming language. This explanation is neither totally comprehensive nor highly detailed.

tldr;

Node.js is an evented I/O framework for the V8 JavaScript engine. It is intended for writing scalable network programs such as web servers.

Long version:

Event-driven programming

Event-driven programming is the idea that events control of the flow of a program. When an event occurs, code registered to handle the event is executed. When performing I/O, traditional programming is synchronous, meaning that an executing thread must wait for the I/O operation to complete before it can continue its execution. Solutions such as multi-threading were devised in order to improve CPU productivity by switching between threads when a thread blocks. Multi-threading does however introduce the overhead of switching between threads and remembering each thread’s context.

At the heart of NodeJS is an event loop that performs two tasks: Check to see if an event has occurred and if so, execute the registered event handler. This allows NodeJS to maintain a single thread that is constantly working, executing event handlers as events occur.

NodeJS is JavaScript

JavaScript–the most popular programming language in the world–is the language of NodeJS. JavaScript has the concept of a closure: a function which remembers the context in which is was declared, allowing it to access that same context when it is executed later. This is perfect for event-driven programming. The programmer can register functions as event handlers, and when the event finally occurs these functions are then executed in the context in which the programmer intended. Along with this come all the other features (and idiosyncrasies) of JavaScript: basic data types, prototypal inheritance, loops, conditionals, etc. There is no JavaScript Standard Library, but NodeJS does come with a core library.

Buffers

NodeJS was originally written to handle text–specifically HTML. The Buffer class was introduced to allow NodeJS to handle binary data. Buffers are chunks of memory allocated outside of the JavaScript VM and are therefore immune to some of the normal effects of garbage collection. Buffers can be sliced and copied. The individual bytes of a Buffer can be manipulated. Buffers can be created from Strings of various encodings, and can be converted into Strings of various encodings. Buffers give NodeJS a range of capabilities that increase the usefulness of NodeJS.

NodeJS Module System

NodeJS does away with the global namespace and implements the CommonJS standard. Files and modules have a one-to-one relationship. Each file chooses exactly what will be publicly exposed by the file’s module when it is loaded by other modules. NodeJS looks for core modules first, then modules with relative path names, and finally looks in “./node_modules” when searching for modules. Each module is cached the first time it is loaded, so the contents of each module are only initialized once.

The NodeJS core library provides the developer with a number of tools for performing I/O, working with HTTP, files, the OS, streams, and much more. In addition, npmjs.org is a large repository of community and open source packages for NodeJS. NodeJS is at home in small, rapidly developing products, probably because NodeJS and its ecosystem are still (relatively) small and under rapid development.

Try it! It’s rediculously easy to get started and hard to drop once you get going.

Building large apps with Angular.js

Thu, 01 Aug 2013 00:00:00 +0000

This post came out of my presentation at a UtahJS meetup. You can even go see my slides.

New to AngularJS? Confused by directive mumbo-jumbo? Giddy over Angular’s magic and your new productivity? Jaded by gotchas you didn’t see coming? Enjoying the zen of Angular?

Whatever your experience with Angular and whatever size of project you’re working on, there will come a day when you encounter Angular in the wild being used on a large project. Does that sound like a dream come true or are you still wary? Either way, you will inevitably run into a problem that Angular does not solve for you. Will you survive?

If you’ve needed to: - Organize your files - Name your files - Lazy-load your code - Serialize application state to the URL - Derive application state from the URL - Manage a Model layer - Do smart caching - Work with a RESTful interface (for real) - Use a 3rd-party lib with Angular

Then you’ve already met the beast.

Angular is not the framework to end all frameworks, however, never before have I derived so much pleasure from web development. Not with NodeJs, not with NoSQL, not with BackboneJS. To misquote @ryanflorence: “I’m Sick of the Web: [Angular]’s Healing Balm”.

My first few weeks with AngularJS I was like a kid on Christmas morning, unwrapping presents as fast as I could and running around showing everybody. Then my new race car broke after 10 loops around the track, I found that none of my previous toys played nice with my new ones, and I realized I would need a Ph.D. to understand my new book “Directives for Dummies”. After a few months of hate/love, things started to click. Directives became my best friends, Angular best practices got me up and running, and I began derive real satisfaction from my work.

Now before you think it’s all fun and games, here are some points to consider as you embark on your journey building large apps with Angular:

Convention vs Configuration

When a framework embraces conventions, developers familiar with the framework can move from project to project with minimal “ramp up” time in order to become familiar with each project. It basically comes down to familiarizing oneself with the project’s business domain. The purpose of conventions is to improve:

“Conventionless” frameworks result in fragmentation, meaning that one developer’s use of a framework can differ wildly from another’s. Example: BackboneJS. An excellent tool in and of itself—but decidedly lacking in enforced conventions. Have you ever seen two Backbone developers do something the exact same way? They might look at each others’ project and have no idea what is going on. Freedom has its downsides.

In regard to convention, AngularJS is a little on the light side. AngularJS puts itself forth as a “MVW” framework loosely based on a traditional MVC framework. Angular Controllers setup and add behavior to $scope objects, and Angular’s templates and two-binding make for a nifty View layer, but Angular has virtually no opinion when it comes to your Model layer. You can do whatever you want.

The path to successfully building a large, fast, and stable application with AngularJS lies in finding and following conventions for you and your dev team. The AngularJS documentation doesn’t help much with that, but many developers are becoming experienced with Angular and have shared the conventions that have helped them find success. You can’t commit to writing your large application with AngularJS without paying attention to the mailing list, the GitHub project, and the opinions of Angular’s core contributors.

Model Layer

Large applications often have a lot of data to deal with, so designing a solid Model layer is essential to building and maintaining a stable Angular application. Angular Services provide a useful tool for separating your Model layer or business logic from your View and Controller layers. $rootScope and $scope are useful as the Model layer for small applications, but can quickly become a mass of messy prototypal inheritance chains that may or may not work the way you think they will. For example:

$scope.fruit = 'banana';
var $newScope = $scope.$new();

$scope.fruit; // 'banana'
$newScope.fruit; // 'banana'

$newScope.fruit = 'apple';
$newScope.fruit; // 'apple'

$scope.fruit; // 'banana' // Did you think it would be 'apple'?

In a large AngularJS application it is important to have a source of truth for your data. Keep your data in your Angular Services and use your Controllers to expose your data to your views.

Your services own your data: ```js app.service(‘MyService’, function ($http, $q, $angularCacheFactory) { var _dataCache = $angularCacheFactory(‘dataCache’, { maxAge: 3600000 // items expire after an hour }); /** * @class MyService */ return { manipulateData: function (input) { var output; // do something with the data return output; },

    getDataById: function (id) {
        var deferred = $q.defer();
        if (_dataCache.get(id)) {
            deferred.resolve(_dataCache.get(id));
        } else {
            // Get the data from the server and populate cache
        }
        return deferred.promise;
    }
}; }); ```

Your controllers and directives consume your data: js $scope.$watch(function () { return MyDataService.getMyData(); }, function () { $scope.myData = MyDataService.getMyData(); });

Ultimately, you’ll want your Model layer to support the needs of a large client-side application. Many tools exist. The point is to not let Angular do your Model layer for you, because you’ll be disappointed. Look into something like $resource, restangular, BreezeJS, or even using BackboneJS Models/Collections. Treat your data with respect.

File Organization

Found at the heart of many an argument is the issue of file organization and naming. Where do we put everything? Do we organize by type, form, function, or feature? PascalCase or camelCase? Some frameworks make this decision for you by enforcing a convention. Ruby on Rails, for example, expects to find your controllers in myApp/app/controller/ and your views in myApp/app/views/. This leaves little room for argument or ambiguity. Some frameworks also use naming conventions to find your files. Here is an example taken from the EmberJS website:

App.Router.map(function() {
  this.route("about", { path: "/about" });
  this.route("favorites", { path: "/favs" });
});

When the user visits /, Ember.js will render the index template. Visiting /about renders the about template, and /favs renders the favorites template. Note that you can leave off the path if it is the same as the route name. In this case, the following is equivalent to the above example:

App.Router.map(function() {
  this.route("about");
  this.route("favorites", { path: "/favs" });
});

The AngularJS framework itself does not provide any such conventions. It’s all up to you. Below are some possible solutions.

Monolithic files

The angular-seed project recommends something like the following for project file organization:

partials/
  home.html
  login.html
  users.html
  orders.html
js/
  controllers.js
  directives.js
  filters.js
  services.js
  app.js

This works great for small, focused applications, but quickly becomes untenable with large applications.

Monolithic folders

A step in the right direction, but can quickly become ridiculous. Imagine searching through the controllers/ folder when it contains 100+ files, trying to find the code for some obscure piece of functionality that your product manager wants to tweak.

js/
  controllers/
    homeController.js
    loginController.js
  directives/
    usersDirective.js
    ordersDirective.js
  filters/
  services/
    userService.js
    orderService.js
    loginService.js
partials/
  home.html
  login.html
  users.html
  orders.html
app.js

Organize by feature

I personally like to be able to visually map what I see on the screen to the source files that make it happen. If I am looking at the “users” page then I expect to be able to find all of the code for it in the “users” package/folder. Modifying the “users” page now means making changes to files in one package/folder, instead of performing “shotgun surgery”.

orders/
  directives/
    orders.html
    ordersDirective.js
  services/
    orderService.js
users/
  directives/
    users.html
    usersDirective.js
  services/
    userService.js
home/
  controllers/
    home.html
    homeController.js
    login.html
    loginController.js
  services/
    loginService.js
shared/
  services/
    i18nService.js
  filters/
    i18nFilter.js
app.js

Modules and lazy loading application components

Angular Modules are good for nothing…so far. Except for loading 3rd-party angular code into your app and mocking during testing. Other than that, there is no reason to use more than one module in your app. Misko said of multiple modules: “[you] should group by view since views will be lazy loaded in near future”. I’d love for someone on the Angular team to enlighten us on what their plans are for that.

Angular does not officially support lazy loading of components. While different workarounds exist, they can result in undefined behavior because Angular expects everything to be loaded during the bootstrap phase. Kudos to Ifeanyi on a lazy-loading solution.

Here’s the basic idea: ```js var app = angular.module(‘app’, []);

app.config(function ($controllerProvider, $compileProvider, $filterProvider, $provide, $animationProvider) { // save references to the providers app.lazy = { controller: $controllerProvider.register, directive: $compileProvider.directive, filter: $filterProvider.register, factory: $provide.factory, service: $provide.service, animation: $animationProvider.register };

// define routes, etc. }); ```

Lazy-load dependencies on a per-route basis: js $routeProvider.when('/items', { templateUrl: 'partials/items.html', resolve: { load: ['$q', '$rootScope', function ($q, $rootScope) { var deferred = $q.defer(); // At this point, use whatever mechanism you want // in order to lazy load dependencies. e.g. require.js // In this case, "itemsController" won't be loaded // until the user hits the '/items' route require(['itemsController'], function () { $rootScope.$apply(function () { deferred.resolve(); }); }); return deferred.promise; }] } });

itemsController.js js // reference the saved controller provider app.lazy.controller('ItemsController', function ($scope) { // define ItemsController like normal });

items.html ```html

; ;

; ```

Understand the $scope life cycle

$scope is the lifeblood of AngularJS. You cannot build a large application with AngularJS and avoid the intricacies of the $scope life-cycle. The $rootScope of your application and all of its child $scopes contain $watch expressions. There is a $watch expression for everything you put onto $scope. This is the magic of Angular’s two-way data-binding.

Angular continuously runs what’s called a $digest loop that checks each $watch expression to see if the value being watched has changed. If it has changed, than Angular executes all of the listeners for that variable. This can happen many times in a second. It is important for your watch expressions to be fast and idempotent. Performance can become an issue if you attach functions as $watch expressions to your $scope. These functions will be executed many times and can slow down performance. If any of the listeners fired by changing $watch expressions create yet more changes, which kick off more $digest loops which end up firing yet more listeners, then performance can be adversely affected.

3rd-party integration with AngularJS

If you’ve spent any real amount of time with Angular than you’ve probably run into problems trying to make 3rd-party libraries work with Angular. If you’re building a large application, chances are you need to integrate several such libraries with your app. Angular thrives on its $digest loop, giving you the two-way data-binding magic. 3rd-party libraries don’t know what Angular does. If your 3rd-party library changes something in the DOM, or returns you a value via an AJAX call, Angular doesn’t know about it and continues doing its thing, none the wiser. The keys to 3rd-party integration with Angular are $scope.$apply(), $scope.$evalAsync, $q.when(), and $timeout.

When something happens with a 3rd-party library, then you’ll probably need to manually kick off a $digest loop via $scope.$apply(). This way Angular can react to whatever your 3rd-party library did. Angular’s $q promise library is a very useful tool for asynchronously resolving the result of whatever your 3rd-party is going to do. Doing something like:

$scope.$apply(function () {
  // do something with 3rd-party lib
});

$timeout(function () {
  // do something with 3rd-party lib
}, 0);

$timeout causes Angular to automatically do a $scope.$apply() after the anonymous function is executed (which isn’t executed until the next browser event loop).

Learning AngularJS is a roller coaster ride, but ultimately results in increased productivity and flexibility in building large applications.

Power up $http with caching

Wed, 29 May 2013 00:00:00 +0000

Intro
LRU Cache
Setting a default cache
Advanced Caching

Intro

Angular.js rocks and you’re flying high making AJAX requests left and right. Inject $http, shoot off a request and boom—the promise-based service hits your error or success callback.

$http.get('/foo/bar/' + itemId)
  .success(function (data) {
    data; // { foo: 'bar' }
  })
  .error(function (data, status, headers, config) {
    // uh oh
  });

Okay, so you’ve got your data from your backend—now what? This particular bit of data doesn’t change very often, and you’re wondering why your client repeatedly makes the same request for the same data—what a waste! Save your users some time and bandwidth and tell that request to use caching!

$http.get('/foo/bar/' + itemId, { cache: true })
  .success(function (data) {
    data; // { foo: 'bar' }
  })
  .error(function (data, status, headers, config) {
    // uh oh
  });

Sweet! Now, the first time $http sends a GET request to /foo/bar/123, for example, the response will be stored in a cache named “$http”. This cache is created by Angular’s $cacheFactory as the default cache for the $http service when Angular boots up. { cache: true } tells the $http service to cache the response to that particular request in $http’s default cache. You don’t have to do anything else. Any subsequent requests to /foo/bar/123 will simply use the cached reponse. Neat!

If you want you can actually reference $http’s default cache and retrieve items, remove items, clear the cache, etc. Just inject $cacheFactory into whatever you’re working with, and reference $http’s default cache via:

var $httpDefaultCache = $cacheFactory.get('$http');

You can retrieve the cached response to the above GET requested by using the absolute url of the request.

var cachedData = $httpDefaultCache.get('http://myserver.com/foo/bar/123'); // { foo: 'bar' }

You can clear that item from the cache:

$httpDefaultCache.remove('http://myserver.com/foo/bar/123');

Or clear the whole cache:

$httpDefaultCache.removeAll();

See $cacheFactory for a complete reference.

LRU Cache

What if you don’t want $http’s default cache to store every response? Simple: turn it into an LRU Cache (Least Recently Used).

// Create a new cache with a capacity of 10
var lruCache = $cacheFactory('lruCache', { capacity: 10 });

// Use the new cache for this request
$http.get('/foo/bar/' + itemId, { cache: lruCache })
  .success(function (data) {
    data; // { foo: 'bar' }
  })
  .error(function (data, status, headers, config) {
    // uh oh
  });

The reponse to each request to /foo/bar/:itemId will be cached, but this time the cache only has a capacity of 10. When the eleventh unique request is made the least recently accessed item will be removed from the caching, keeping the total number of cached items at 10. This cache maintains a list of its items in order of how recently they have been accessed so it knows which one to remove when storing a new item would exceed the capacity.

Setting a default cache

As shown in the LRU example you can tell an $http request to use a cache other than $http’s default cache, but what if you wants to change $http’s default cache? It’s easy:

$http.defaults.cache = $cacheFactory('myNewDefaultCache', { capacity: 100 });

$http will now use myNewDefaultCache as its default cache.

Advanced Caching

What if you want to cache data to improve user experience, but the data is liable to change once a day, or every few hours, etc. You would want to make sure your cached data gets cleared at least once a day, every ten minutes, etc. Unfortunately Angular’s $cacheFactory does not provide any such capabilities.

You could hack something together using setInterval() or setTimeout(), but you don’t want to do that. To solve this problem I created angular-cache, a drop-in Angular module that gives you access to $angularCacheFactory, which creates caches with more capabilities. With angular-cache your caches can periodically clear themselves with cacheFlushInterval. When adding to a cache you can specify a maxAge, which is the maximum amount of time that particular item will be in the cache before it is automatically removed. Or you can specify a maxAge for the whole cache which will be applied to every item added to the cache.

I’ll refer you to the angular-cache documentation for further reference.

Happy caching!

Designing for Testability

Fri, 17 May 2013 00:00:00 +0000

My talk given at UtahJSConf 2013

Do you dread writing tests? Are you frustrated with un-testable code? Wish you had confidence in your application?

What about “no pain, no gain”? Come learn design principles that will give you confidence in your code—without the pain.

Designing for testability means adhering to sound design principles. A core benefit of solid design is insight into the internal state and activities of your program. “Testable” doesn’t mean you can easily achieve 100% code coverage—it means you can easily verify you’ve created the right program and then validate your program’s correctness.

Learn the What, Why, and How of:

Abstraction
Decomposition
Design by Contract
Law of Demeter
Orthogonality
Single Responsibility
DRY
Logging

Beginners welcome. A must for intermediates. A great refresher for all.

Designing for Testability

i18n.js vs jquery.i18n.properties.js

Wed, 06 Feb 2013 00:00:00 +0000

Internationalization is a big deal these days, but implementing it is still a pain sometimes. With the rise in popularity of JavaScript-heavy applications using tools like Require.js, Backbone.js, Handlebars.js, etc., one naturally seeks a solution to the internationalization problem that fits into the paradigms of these tools. I kept a couple of points in mind while searching for a solution:

The tool introduces no new dependencies into the build process (e.g. I don’t want to have to install Ruby)
The tool allows storage of i18n text in simple, easy-to-use, and preferably super common formats (e.g. JSON, or Java’s .properties)
The tool has a small footprint on projects
The tool lets me to easily access the i18n text inside my templates I found a number of tools out there, but two jumped out at me: i18n.js (for Require.js) and jquery.i18n.properties.js

i18n.js

A plugin for Require.js, i18n.js loads i18n text files as dependencies. i18n files are .js files that use the “define” wrapper function. The default i18n file (with no locale specified) could look like this:

path/to/i18n/files/i18n_module_A.js js define({ "root": { "someText": "A short sentence", "otherText": "pink pants" }, "ru-RU":true, "fr-fr":false }); The “root” is the default text. “ru-RU”:true tells i18n.js that the application supports Russian with region code RU, therefor i18n.js should expect to be able to find files in an ru-RU folder that provide the Russian text. Therefore I should also have the file:

path/to/i18n/files/ru-RU/i18n_module_A.js js define({ "someText": "короткое предложение", "otherText": "розовые штаны" }); “fr-fr”:false tells i18n.js that “fr-fr” is not supported, so even if the browser’s locale is fr-fr, i18n.js will use the default text in “root”. If module_A.js needs the text in i18n_module_A.js, then it loads the text like a dependency:

module_A.js ```js define([ ‘someDep’, ‘i18n!path/to/i18n_module_A’ ], function (SomeDep, i18n_module_A) {

// i18n_module_A is a JavaScript Object.

// Prints “a short sentence” if the browser’s locale is not supported by the application // Prints “короткое предложение” if the browser’s locale matches “ru-RU” console.log(i18n_module_A.someText);

// Prints “pink pants” if the browser’s locale is not supported by the application // Prints “розовые штаны” if the browser’s locale matches “ru-RU” console.log(i18n_module_A.otherText); }); ``` i18n.js also supports country codes only (e.g. “ru”):

path/to/i18n/files/ru/i18n_module_A.js js define({ "someText": "короткое предложение", "otherText": "розовые штаны" }); Loading the i18n text as dependencies proves to be pretty nifty. During the r.js optimization the default text files get in-lined into the build, but there will always end up being HTTP requests for specific country/region files. In the Require.js callback function i18n text is loaded into a JavaScript Object automatically, which can simple be passed to a templating engine’s render function. The template can then pick text off the object. It made for a very small amount of code to actually implement internationalization via i18n.js. You simply depend on an i18n file and pass the resulting JavaScript Object to your template. Simple.

However, i18n.js requires the i18n files to be in some obscure format. If you don’t need any server-side code (that’s not Node.js) to read these files then it’s not a big deal, but languages like Java already use the well-known .properties format, with which translation companies are familiar and have tools to parse. In my case all of my i18n files are in the .properties format, so I had to write scripts to convert the .properties files to the .js files consumable by i18n.js, which was a hassle and an unnecessary addition to the build process.

Another thing against i18n.js is that it does not support parameterization of strings. For example, if I need to be able to insert a user’s name into a sentence, then I have to break the sentence up into two pieces. Very messy.

Final thoughts on i18n.js: Trivial to setup with Require.js. Non-trivial to make it work with other file format’s and pre-existing standards. Lack of parameterization is a problem.

jquery.i18n.properties.js

Who wouldn’t jump at the chance to add another jQuery plugin to their site? Luckily it’s only 4.3KB minified. The convenience of this plugin, at least for me, is that it directly consumes .properties files. Now my Java services can consume the same i18n files as the frontend.

Messages.properties # This line is ignored by the plugin msg_hello = Hello msg_world = World msg_complex = Good morning {0}! Messages_ru_RU.properties # This line is ignored by the plugin msg_hello = привет msg_world = мир msg_complex = доврое утро {0}! .properties files are loaded with an Ajax call:

Loading a .properties file ```js // This will initialize the plugin // and display “Good morning John!” jQuery.i18n.properties({ name:’Messages’, path:’path/to/i18n/files/’, mode:’map’, language:’ru_RU’, callback: function() { // I specified mode: ‘map’ because the ‘vars’ mode // will add a lot of global JS vars to the page.

// Accessing a simple value through the map
$.i18n.prop('msg_hello');

// prints 'привет'
alert($.i18n.prop('msg_hello'));   } }); ``` Another great plus for this plugin is that is supports parameterization:

parameterization js // prints доброе утро John! alert($.i18n.prop('msg_complex', 'John')); // does the same as above alert($.i18n.map.msg_complex('John')); Initially I was worried that using this plugin would result in a lot more lines of code in the JavaScript, as I thought that I would need to manually extract each line of text from the .properties files. This plugin does not put all of the i18n text into a JavaScript object like the i18n.js plugin does. However, it was rather simple to write a helper for Dust.js that allows me to access i18n strings loaded by jQuery directly in my templates:

Dust.js helper js dust.helpers.i18n = function (chunk, ctx, bodies, params) { var key = dust.helpers.tap(params.key, chunk, ctx); return chunk.write($.i18n.map[key]); }; and then in the template:

Accessing i18n strings in the template ```html

{@i18n key="msg_hello" /}

``` Final thoughts on jQuery.i18n.properties.js: I really appreciate this plugin’s support for parameterization of strings. More importantly, it consumes .properties files which is excellent.

Conclusion

With the help of the Dust.js helper function it ends of being much more convenient to work with the jQuery.i18n.properties.js plugin, rather than the i18n.js plugin for Require.js. I haven’t looked deeply into other solutions for internationalization, but the jQuery plugin meets my needs just fine.

Maven and r.js optimization

Fri, 01 Feb 2013 00:00:00 +0000

Using Maven to manage a large project has it’s advantages, until you need to do something that doesn’t fit into the Maven’s defined context. Tools based on composability provide components that can be combined in various ways to accomplish needed tasks. Maven—a contextual tool—provides a lot of functionality out of the box, but ultimately requires users to conform to Maven’s way of doing things, not allowing the user to simple string together commands to perform custom tasks.

I personally am a big fan of using Grunt.js—a composable tool—for performing tasks on my JavaScript (like r.js optimization). However, Grunt introduces a dependency on Node.js—a JavaScript run-time. Maven’s design does not sit well with running external scripts during a Maven build. How can these scripts communicate back to Maven and report on their success, failure, or something in between? They can’t. Maven watches for a successful return code, but that’s it. External scripts are used because Maven didn’t provide the tools to perform the tasks, so 3rd-party tools were brought into the picture. But because the extra tools weren’t grown in Maven’s context, they’re on their own.

I messed around with having Maven run external node.js scripts for a while, but it was ugly. I decided to give mcheely’s requirejs-maven-plugin a try. His plugin takes the r.js optimizer and shoves it into Maven’s context. And you know what? It works pretty well.

Configuration can be as simple as: ```xml

com.github.mcheely requirejs-maven-plugin 1.0.4 process-classes optimize ${basedir}/src/main/webapp/resources/js/app.build.js false false

```

By using this plugin (and a few others like the minify-maven-plugin) here at work we’ve successfully eliminated our dependency on Node.js for builds, which makes development environments easier to setup for everybody and means less things for Java developers to have to learn. I have nothing against Node.js here—I really like it, but the existence of plugins like this make life with Maven (and other devs) a little easier.