UserTiming compression and decompression
npm install usertiming-compressionv0.1.9
Licensed under the MIT license
usertiming-compression.js compresses data from UserTiming. A
companion script, usertiming-decompression.js, converts the compressed data back to the original form.
UserTiming is a modern browser performance
API that gives developers the ability the mark important events (timestamps) and measure durations (timestamp deltas)
in their web apps. The PerformanceTimeline has several methods such asperformance.getEntriesByType('mark') or performance.getEntriesByType('measure') that return each mark or
measure's startTime (timestamp) and duration (for measures).
usertiming-compression.js applies several data-compression techniques to reduce the size of your serialized
UserTiming data to 10-15% of it's original size in many cases. See
this blog post for a description of these techniques.
usertiming-decompression.js is a companion script that will take the compressed UserTiming data and
build it back to its original UserTiming form (eg. performance.getEntriesByType('mark')) for analysis.
Releases are available for download from GitHub.
__Development:__ (UMD) usertiming-compression.js - 20kb
__Development:__ (window.UserTimingCompression) usertiming-compression.vanilla.js - 20kb
__Production:__ (UMD) usertiming-compression.min.js - 4.0kb minified, 1.6kb gzipped
__Production:__ (window.UserTimingCompression) usertiming-compression.vanilla.min.js - 3.8kb minified, 1.6kb gzipped
__Development:__ (UMD) usertiming-decompression.js - 16kb
__Development:__ (window.UserTimingCompression) usertiming-decompression.vanilla.js - 15kb
__Production:__ (UMD) usertiming-decompression.min.js - 3.7kb minified, 1.5kb gzipped
__Production:__ (window.UserTimingCompression) usertiming-decompression.vanilla.min.js - 3.5kb minified, 1.5kb gzipped
usertiming-compression.js is also available as the npm usertiming-compression module. You can install
using Node Package Manager (npm):
npm install usertiming-compression
usertiming-compression.js is also available via bower. You can install using:
bower install usertiming-compression
Compression and decompression can be done on the command line via:
node cmd.js
``
$ node cmd.js --help
Usage: cmd [options] [command]
Commands:
decompress
compress
Options:
-h, --help output usage information
-V, --version output the version number
-o, --output
-p, --pretty Pretty JSON
-v, --verbose Verbose debugging
`
Please see the W3C UserTiming API Reference for details on how to use the
UserTiming API.
To include usertiming-compression.js, include it via a script tag:
`html`
Once included in the page, a top-level UserTimingCompression object is available on window.
If AMD or CommonJS environments are detected, you can use the UMD version:
`html`
From the NPM module:
`js`
var UserTimingCompression = require("usertiming-compression").UserTimingCompression;
To get a map of compressed UserTiming names to values, you can call:
`js`
var utMap = UserTimingCompression.getCompressedUserTiming(options);
// {
// "mark1": "2s",
// "mark2": "5k",
// "mark3": "8c"
// }
If you have a map of mark / measure names you want to use, pass them in
as options.map:
`js`
var utMap = UserTimingCompression.getCompressedUserTiming({
map: {
"mark1": 0,
"mark2": 1,
"mark3": 2
}
});
// {
// "0": "2s",
// "1": "5k",
// "2": "8c"
// }
If you want to further compress this list for a format suitable for URL transmission (e.g. on a query string), you
can use compressForUri():
`js`
var utData = UserTimingCompression.compressForUri(utMap);
// ~(m~(ark~(1~'2s~2~'5k~3~'8c)))
#### UserTimingCompression.getCompressedUserTiming(options)
Gathers all UserTiming marks and measures from the root HTML page and all accessible IFRAMEs.
Arguments:
* options (optional)options.map
* : A map of names to indexes to use for compression.options.from
* : The minimum startTimeoptions.to
* : The maximum startTimeoptions.window
* : window object that will be queried for UserTiming data
Returns: A map of names to compressed values.
`js`
{
"mark1": "2s",
"mark2": "5k",
"mark3": "8c"
}
#### UserTimingCompression.compressForUri(map)
Takes the output of getCompressedUserTiming() and converts it into a string suitable for URI encoding.
Arguments:
* map A map of names to string values
Returns: A map of names to compressed values.
``
"~(m~(ark~(1~'2s~2~'5k~3~'8c)))"
Note: The first character of the string denotes what type of compression
is used:
1. ~ is optimized Trie (JSURL) compression0
2. is a tilde array1
3. is a mapped array
To include usertiming-decompression.js, include it via a script tag:
`html`
Once included in the page, a top-level UserTimingDecompression object is available on window.
If AMD or CommonJS environments are detected, you can use the UMD version:
`html`
From the NPM module:
`js`
var UserTimingDecompression = require("usertiming-compression").UserTimingDecompression;
To decompress your resources, you can call:
`js`
var original = UserTimingDecompression.decompressUserTiming(utData);
#### UserTimingDecompression.decompressUserTiming(data)
Decompresses data from a URI-encoded form.
Arguments:
* data Data compressed via compressForUri()
Returns: The original UserTiming data
`js`
[
{"duration":0,"entryType":"mark","name":"mark1","startTime":100},
{"duration":0,"entryType":"mark","name":"mark1","startTime":150},
{"duration":0,"entryType":"mark","name":"mark1","startTime":500}
]
Tests are provided in the test/ directory, and can be run via mocha:
mocha test/*
Or via gulp:
gulp test
* v0.1.0 - 2015-12-10: Initial version
* v0.1.1 - 2016-04-04: getCompressedUserTiming() gathers Measures that end after the specified fromgetCompressedUserTiming()
* v0.1.2 - 2016-04-04: Protect against X-O frame access that crashes some browsers
* v0.1.3 - 2016-07-25: accepts an alternate window param passed into optionsduration
* v0.1.4 - 2016-08-10: Round values on Measures to nearest milliseconddist/
* v0.1.5 - 2017-10-01: Fixed NPM entry point
* v0.1.6 - 2018-11-21: Changed build process to produce UMD (for Node/require) and "Vanilla" (for Browser) files in dist/
* v0.1.7 - 2018-11-21: Ensure is published in bower.vanilla.js` in NPM
v0.1.8 - 2018-11-21: Also include
* v0.1.9 - 2019-09-17: Fix: Compression on Trie nodes that are prefixes of another
Parts of JSURL were incorporated into this library. This project builds upon the
work of ResourceTiming Compression, with
guidance from Philip Tellis and others at SOASTA.