Avoid primitive-obsession-related problems by adding behavior to Angular resources using Underscore extend function

One of the problems I found while working on a legacy Angular application last year, was resources with deeply nested structures that were being accessed directly from many different places.

That code was revealing too much about the resources inner structure and that meant that the code that interacted with the resources was spread all over therefore generating a lot of duplication. That made it really hard to change and understand.

It was suffering from a severe case of primitive obsession in the form of directly using raw resources.

To prevent that from happening in the Angular application we are developing now, we have added behavior to Angular resources using Underscore extend function. By doing it, we have managed to hide the inner structure of the resources from its users and also created an object that has attracted the resource-handling code that was before spread all over.

These strategy has put us in a much better position. Now if the structure of the JSON data of a resource changes for any reason, we have only one place to go to adapt to that change.

It also has improved the overall readability of the code by making it possible to give proper names to the different resource-handling functions.

Here it's an example from our code:

	app.factory('Track', [
	'$http',
	'$resource',
	'dateStringsInsideObjectsIntoDates',
	'appendTransform',
	'ApiBaseUrl',
	'trackMethods',
	function (
	$http,
	$resource,
	dateStringsInsideObjectsIntoDates,
	appendTransform,
	ApiBaseUrl,
	trackMethods
	) {
	var Track = $resource(
	ApiBaseUrl + '/tracks/:track_slug',
	{'track_slug': '@slug'}, {
	'get': {
	method: 'GET',
	transformResponse: appendTransform(
	$http.defaults.transformResponse,
	function (value) {
	dateStringsInsideObjectsIntoDates.convert(value);
	return value;
	}
	)
	},
	'query': {
	method: 'GET',
	isArray: true,
	transformResponse: appendTransform(
	$http.defaults.transformResponse,
	function (value) {
	angular.forEach(value, function (item) {
	dateStringsInsideObjectsIntoDates.convert(item);
	});
	return value;
	}
	)
	},
	'getTracksWithoutData': {
	method: 'GET',
	isArray: true,
	ignoreLoadingBar: true
	},
	'update': { method: 'PUT' },
	'delete': { method: 'DELETE' }
	}
	);
	_.extend(Track.prototype, trackMethods);
	return Track;
	}
	]);

view raw TrackResource.js hosted with ❤ by GitHub

Notice the use of the extend function to add the behavior in TrackMethods to the prototype of Track resource.

TrackMethods is an object containing several functions that hide the inner structure of the Track resource and make its use more readable:

	app.factory('trackMethods', [
	'ApiKey',
	'measure',
	function (ApiKey, measure) {
	return {
	getUrl: function () {
	return this.resource_uri +
	'?apikey=' + ApiKey;
	},
	getStatisticsValueFor: function (statType) {
	if (this.statisticIsNotDefined(statType)) {
	return 0;
	}
	return measure.getValue(
	statType,
	this.statistics.data[statType]
	);
	},
	statisticIsNotDefined: function (statType) {
	return _.isUndefined(this.statistics) ||
	_.isUndefined(this.statistics.data) ||
	_.isUndefined(this.statistics.data[statType]);
	},
	getStatistics: function () {
	return this.statistics.data;
	},
	getChartFor: function (graphicType, xAxis) {
	return this.graphics.data[graphicType][xAxis];
	},
	getXAxisUnits: function (graphicType, currentSelectedXAxis) {
	var xAxisBySelectedXAxis = {
	"with_respect_to_distance": "distance",
	"with_respect_to_time": "time"
	},
	xAxis = xAxisBySelectedXAxis[currentSelectedXAxis];
	return this.graphics.data[graphicType]["units"][xAxis];
	},
	getYAxisUnits: function (graphicType) {
	var yAxisByGraphicType = {
	"speed_graphics": "speed",
	"elevations_graphics": "elevation",
	"cadence_graphics": "cadence",
	"heart_rate_graphics": "heart_rate"
	},
	yAxis = yAxisByGraphicType[graphicType];
	return this.graphics.data[graphicType]["units"][yAxis];
	},
	getChartsKeys: function () {
	return _.keys(this.graphics.data);
	}
	};
	}
	]);

view raw TrackMethods.js hosted with ❤ by GitHub

The only restriction we put ourselves is that behavior extensions like TrackMethods can't have any state.

Currently TrackMethods contains only accessors, but it will surely grow as the application evolves. All the functions in TrackMethods were discovered in other parts of the code and moved into it. We try to stay alert at new opportunities to attract more code into these behavior extensions.

Another advantage we've found is that these behavior extensions can be easily tested using fake resources.

These are TrackMethods current tests:

	"use strict";
	describe("trackMethods factory", function () {
	var trackMethods;
	beforeEach(module("agora"));
	beforeEach(function () {
	module(function ($provide) {
	$provide.value('ApiKey', "fakeApiKey");
	})
	});
	beforeEach(inject(function (_trackMethods_) {
	trackMethods = _trackMethods_;
	}));
	describe("added behavior to get information about Track file URL", function () {
	it("adds behavior to Track in order to get the Url needed to get the Track file",
	inject(function (ApiKey) {
	var fakeTrack = {
	resource_uri: "a_track_resource_uri"
	};
	_.extend(fakeTrack, trackMethods);
	expect(fakeTrack.getUrl())
	.toBe("a_track_resource_uri" + '?apikey=' + ApiKey);
	})
	);
	});
	describe("added behavior to get information about statistics", function () {
	var statisticsData = {
	distance: {
	val: 12.9,
	unit: "km"
	},
	duration: {
	val: 20.5,
	unit: "min"
	}
	},
	fakeTrackWithStatistics = {
	statistics: {
	data: {
	distance: {
	val: 12.9,
	unit: "km"
	},
	duration: {
	val: 20.5,
	unit: "min"
	}
	}
	}
	};
	it("adds behavior to Track in order to get the value of a given statistics type from the Track", function () {
	_.extend(fakeTrackWithStatistics, trackMethods);
	expect(fakeTrackWithStatistics.getStatisticsValueFor('distance'))
	.toBe('12.90');
	expect(fakeTrackWithStatistics.getStatisticsValueFor('duration'))
	.toBe('00:20:30');
	});
	it("adds behavior to Track in order to get the statistics from the Track", function () {
	_.extend(fakeTrackWithStatistics, trackMethods);
	expect(fakeTrackWithStatistics.getStatistics())
	.toEqual(statisticsData);
	});
	});
	describe("added behavior to get information about charts", function () {
	var fakeTrackWithCharts;
	beforeEach(function () {
	fakeTrackWithCharts = {
	graphics: {
	data: {
	speed_graphics: {
	units: {
	distance: "km",
	speed: "km/h",
	time: "min"
	},
	with_respect_to_distance: [
	[0, 84.347023678293046],
	[0.00759832001978291, 78.967678756],
	[0.0199020023655221, 70.5676347023]
	],
	with_respect_to_time: [
	[0, 84.347023678293046],
	[0.25, 78.967678756],
	[0.43333333333333, 70.5676347023]
	]
	},
	elevations_graphics: {
	units: {
	distance: "km",
	elevation: "m",
	time: "min"
	},
	with_respect_to_distance: [
	[0, 0],
	[0.00759832001978291, 2.3235974923137],
	[0.0199020023655221, 4.0266596767875]
	],
	with_respect_to_time: [
	[0, 0],
	[0.25, 2.3235974923137],
	[0.43333333333333, 4.0266596767875]
	]
	}
	}
	}
	};
	});
	it("adds behavior to Track in order to get the data of a specific chart from the Track", function () {
	_.extend(fakeTrackWithCharts, trackMethods);
	expect(fakeTrackWithCharts.getChartFor('elevations_graphics', 'with_respect_to_distance'))
	.toEqual([
	[0, 0],
	[0.00759832001978291, 2.3235974923137],
	[0.0199020023655221, 4.0266596767875]
	]);
	});
	it("adds behavior to Track in order to get the units of a specific axis of a chart from the Track", function () {
	fakeTrackWithCharts.graphics.data.speed_graphics.units.distance = "m";
	fakeTrackWithCharts.graphics.data.speed_graphics.units.time = "hour";
	fakeTrackWithCharts.graphics.data['cadence_graphics'] = {
	units: {distance: 'km', cadence: 'rpm', time: 'min'}
	};
	fakeTrackWithCharts.graphics.data['heart_rate_graphics'] = {
	'units': {distance: 'km', heart_rate: 'bpm', time: 'min'}
	};
	_.extend(fakeTrackWithCharts, trackMethods);
	expect(fakeTrackWithCharts.getXAxisUnits('elevations_graphics', 'with_respect_to_distance'))
	.toEqual("km");
	expect(fakeTrackWithCharts.getXAxisUnits('elevations_graphics', 'with_respect_to_time'))
	.toEqual("min");
	expect(fakeTrackWithCharts.getXAxisUnits('speed_graphics', 'with_respect_to_distance'))
	.toEqual("m");
	expect(fakeTrackWithCharts.getXAxisUnits('speed_graphics', 'with_respect_to_time'))
	.toEqual("hour");
	expect(fakeTrackWithCharts.getYAxisUnits('elevations_graphics'))
	.toEqual("m");
	expect(fakeTrackWithCharts.getYAxisUnits('speed_graphics'))
	.toEqual("km/h");
	expect(fakeTrackWithCharts.getYAxisUnits('cadence_graphics'))
	.toEqual("rpm");
	expect(fakeTrackWithCharts.getYAxisUnits('heart_rate_graphics'))
	.toEqual("bpm");
	});
	it("adds behavior to Track in order to get the list of chart keys (types of charts, e.g., elevations_graphics, speed_graphics) " +
	"that the Track contains", function () {
	jasmine.addMatchers({toEqualIgnoringOrder: toEqualIgnoringOrder});
	_.extend(fakeTrackWithCharts, trackMethods);
	expect(fakeTrackWithCharts.getChartsKeys()).toEqualIgnoringOrder(["elevations_graphics", "speed_graphics"]);
	});
	});
	function toEqualIgnoringOrder() {
	return {
	compare: function (actual, expected) {
	var actualCopy, expectedCopy;
	if (actual.length !== expected.length) {
	return {
	pass: false
	};
	}
	actualCopy = actual.slice(0);
	expectedCopy = expected.slice(0);
	actualCopy.sort();
	expectedCopy.sort();
	return {
	pass: _.isEmpty(_.difference(actualCopy, expectedCopy)) &&
	_.isEmpty(_.difference(expectedCopy, actualCopy))
	};
	}
	};
	}
	});

view raw TrackMethodsSpec.js hosted with ❤ by GitHub

This strategy of extending Angular resources with behavior is an alternative to encapsulate collection which is working quite well for us to avoid primitive-obsession-related problems.