calstats.js
v2.0.5
Published
JavaScript tool that can generate statistics for calendars by parsing [tags]
Downloads
7
Maintainers
Readme
calstats.js
JavaScript tool that can generate statistics for calendars by parsing [tags]
. Provides:
- Amount of time spent on each client
- Detailed breakdown of tasks within projects
- Total time spent
- Count of events
- "Tree" of the calendar data
This library has adapters for:
- [/src/adapters/google.js](Google Calendar via oauth)
- [/src/adapters/ical.js](ical formatted feed), as delivered by the ical library
You can also use your own adapter, provided it matches the interfaces of the adapters above.
Feel free to write your own adapter and pull request it back to us! See our contributing guidelines
Boundaries
This diagram shows the boundaries of calstats.js and how it fits into your application:
calstats.js is for:
- Generating statistics from calendar data
calstats.js is NOT for:
- Getting the data from your calendar API
- Entering data into a calendar
- Displaying statistics to the user
You must do these things yourself (some examples are below).
Installation
npm install calstats.js
How calstats.js works
calstats.js
parses [tags] out of raw calendar data and uses that to create statistics.
In your calendar, make sure your entries have "[tags] in their subjects". Tags are simply square brackets. You create events in your calendar and write something like [projecta-development]
or [projecta-research]
. For example:
- "[research] investigating AngularJS plugins"
- "[project-a] writing new user interface"
Here is an example of using tags in Google Calendar:
The first "part" of a tag is used as the top level tag. So, if you have [projecta-one]
and [projecta-two]
, this means that the tool can group project a's entries together (exposed using getHighLevelBreakdown()
) and then allow you to drill down into its details (using getBreakdown()
).
API
Instantiate with:
var calstats = require('calstats');
You then need to load data into calstats. It will default to using the ical adapter, which requires the ical library. Here is an example:
var calstats = require('calstats');
var ical = require('ical');
// use the ical library to grab some raw ical data
ical.fromURL(someUrl, {}, function(err, data) {
// load the raw ical data into calstats
calstats
.setStartDate('2015-12-01')
.setEndDate('2016-02-01')
.setRawData(data)
.run();
// calstats is now ready to rock!
});
Once it's ready to rock, you can call the following functions:
getEarliest()
- returns the earliest event date that was found in the ical feed within your specified date rangegetLatest()
- returns the latest event date that was found in the ical feed within your specified date rangegetCount()
- returns the count of events within your specified date rangegetTotalHours()
- returns the total number of hours of the events within your specified date rangegetHighLevelBreakdown()
- returns a breakdown by the top level, for example:
{ research: 6, admin: 3.5, project: 16.5 }
getBreakdown
- returns a full breakdown, for example:
{ research: 6,
admin: 3.5,
'project-c': 4,
'project-b': 4.5,
'project-a': 8 }
getTree
- return a tree-type breakdown. Hour counts are available with the.value
key at any point in the tree. This means that, given input breakdown data like:
{
'radify': 1,
'radify-labs': 1,
'radify-labs-admin': 1,
'radify-labs-calstats': 1,
'radify-labs-radiian': 1,
'radify-labs-radiian-debugging': 1,
'radify-labs-radiian-publishing': 1,
'radify-admin': 1,
'radify-admin-meeting': 1
}
calstats.js can tell you things like:
- 9 hours were spent on all Radify tasks
- 3 hours were spent on all Radify labs radiian tasks
- 1 hour was spent on debugging Radify labs radiian
- 2 hours was spent in total on Radify admin
- 1 hour was spent in Radify admin meeting, and 1 hour in "radify-admin" (expressed as "other")
This means that your client applications can support 'drilling down' into calstats.js data sets.
Example usages
Example API
Here is a simple API that uses the calstats.js
library to return statistics about a calendar. It uses:
- Hapi framework - used for building an API
- ical library - for loading and parsing ical feeds
- calstats.js - this library, used for producing statistics
var Hapi = require('hapi');
var calstats = require('calstats');
var ical = require('ical');
var server = new Hapi.Server();
server.connection({port: 4730, routes: {cors: true}});
server.start(function() {
console.log('Server running at:', server.info.uri);
});
server.route({
method: ['POST'],
path: '/',
handler: function(request, reply) {
ical.fromURL(request.payload.cal, {}, function(err, data) {
calstats
.setStartDate(request.payload.startDate)
.setEndDate(request.payload.endDate)
.setRawData(data)
.run();
reply({
earliest: calstats.getEarliest(),
latest: calstats.getLatest(),
count: calstats.getCount(),
total: calstats.getTotalHours(),
breakdown: calstats.getBreakdown(),
highLevelBreakdown: calstats.getHighLevelBreakdown(),
tree: calstats.getTree()
});
});
}
});
Adapters
calstats.js comes bundled with adapters for:
- [/src/adapters/googleapi.js](Google Calendar via oauth) - results from the Google Calendar API events/list call
- [/src/adapters/icalfeed.js](ical formatted feed), as delivered by the ical library - an ical feed as loaded through the ical library. This is the default adapter.
Feel free to write your own adapter! See our contributing guidelines
To load an adapter, tell calstats.js to use that adapter:
// load the data into calstats using the google calendar adapter to normalise the raw data Google provides
calstats
.setStartDate('2016-01-01')
.setEndDate('2016-02-01')
.setRawData(data)
.setAdapter(calstats.adapters.google)
.run();
calstats
.setStartDate('2016-01-01')
.setEndDate('2016-02-01')
.setRawData(data)
.setAdapter(calstats.adapters.ical)
.run();
Example command line client
- Commander - used for a nice CLI interface
- ical library - for loading and parsing ical feeds
- calstats.js - this library, used for producing statistics
var program = require('commander');
var calstats = require('calstats');
var ical = require('ical');
program
.version('0.0.4')
.option('-i, --ical [url]', 'Private ical link from Google Calendar')
.option('-s, --startDate [startDate]', 'The date to start from, e.g. 2015-05-01')
.option('-e, --endDate [endDate]', 'The date to start from, e.g. 2015-05-08')
.parse(process.argv);
if (!process.argv.slice(2).length) {
program.help();
}
program.parse(process.argv);
ical.fromURL(program.ical, {}, function(err, data) {
calstats
.setStartDate(program.startDate)
.setEndDate(program.endDate)
.setRawData(data)
.run();
console.log("Date range: " + calstats.getEarliest() + " - " + calstats.getLatest());
console.log("count: " + calstats.getCount() + " events");
console.log("total: " + calstats.getTotalHours() + " hours");
console.log("\nHigh level breakdown:");
console.log(calstats.getHighLevelBreakdown());
console.log("\nDetailed breakdown:");
console.log(calstats.getBreakdown());
console.log("\nTree:");
console.log(calstats.getTree());
});
Development
Clone this repo and then install dependencies with:
npm install
Now build the project by running:
gulp
This will create /build/calstats.js
, which is the file that other projects should use, as specified in package.json
.
Note the directory spec
which contains the unit tests for this library.
If you would like to submit code, feel free to create a pull request.