Initial commit

nicjansma · Apr 16, 2013 · b2d6439 · b2d6439
commit b2d6439
Show file tree

Hide file tree

Showing 27 changed files with 10,464 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+/node_modules
+npm-debug.log
+.project
+.settings/
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,6 @@
+deps
+dist
+test
+.npmignore
+.gitmodules
+Gruntfile.js
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -0,0 +1,62 @@
+module.exports = function(grunt) {
+    // Project configuration.
+    grunt.initConfig({
+        pkg: grunt.file.readJSON('package.json'),
+        uglify: {
+            options: {
+                banner: '/*! <%= pkg.name %> v<%= pkg.version %> */\n'
+            },
+            build: {
+                src: 'src/<%= pkg.name %>.js',
+                dest: 'dist/<%= pkg.name %>.min.js'
+            }
+        },
+        jshint: {
+            files: [ 'src/**/*.js', 'test/**/*.js' ],
+            options: {
+                bitwise: true, 
+                camelcase: true, 
+                curly: true, 
+                eqeqeq: true, 
+                forin: true, 
+                immed: true,
+                indent: 4, 
+                latedef: true, 
+                newcap: true, 
+                noempty: true, 
+                nonew: true, 
+                quotmark: true, 
+                jquery: true,
+                undef: true, 
+                unused: true, 
+                strict: true, 
+                trailing: true, 
+                browser: true, 
+                node: true, 
+                white: false,
+                globals: {
+                    define: true,
+                    window: true
+                }
+            }
+        },
+        nodeunit: {
+            all: ['test/*.js']
+        }
+    });
+
+    //
+    // Plugins
+    //
+    grunt.loadNpmTasks('grunt-contrib-uglify');
+    grunt.loadNpmTasks('grunt-contrib-nodeunit');
+    grunt.loadNpmTasks('grunt-contrib-jshint');
+
+    //
+    // Tasks
+    //
+    grunt.registerTask('default', ['jshint', 'uglify']);
+    grunt.registerTask('test', ['nodeunit']);
+    grunt.registerTask('lint', ['uglify']);
+    grunt.registerTask('all', ['nodeunit', 'jshint', 'uglify']);
+};
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -0,0 +1,20 @@
+Copyright (c) 2013 Nic Jansma, http://nicj.net
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,125 @@
+# UserTiming.js
+
+v0.1.0
+
+Copyright 2013 Nic Jansma
+
+http://nicj.net
+
+Licensed under the MIT license
+
+## Introduction
+
+UserTiming.js is a polyfill that adds [UserTiming](http://www.w3.org/TR/user-timing/) support to browsers
+that do not natively support it.
+
+UserTiming is accessed via the [PerformanceTimeline](http://www.w3.org/TR/performance-timeline/), and requires
+[``window.performance.now()``](http://www.w3.org/TR/hr-time/) support, so UserTiming.js
+adds a limited version of these interfaces if the browser does not support them (which is likely the case if the browser
+does not natively support UserTiming).
+
+As of 2013-04-15, UserTiming is natively supported by the following browsers:
+
+* IE 10+
+* Chrome 25+ (prefixed)
+
+UserTiming.js has been verified to add UserTiming support to the following browsers:
+
+* IE 6-9
+* Firefox 3.6+ (previous versions not tested)
+* Safari 4.0.5+ (previous versions not tested)
+* Opera 10.50+ (previous versions not tested)
+
+UserTiming.js will detect native implementations of UserTiming, ``window.performance.now()`` and
+the PerformanceTimeline and will not make any changes if those interfaces already exist.  When a prefixed version
+is found, it is copied over to the unprefixed name.
+
+## Download
+
+Releases are available for download from [GitHub](https://github.com/nicjansma/usertiming.js).
+
+__Development:__ [usertiming.js](https://github.com/nicjansma/usertiming.js/raw/master/src/usertiming.js)
+    - 18.1kb
+
+__Production:__ [usertiming.min.js](https://github.com/nicjansma/usertiming.js/raw/master/dist/usertiming.min.js)
+    - 1,187b (minified / gzipped)
+
+usertiming.js is also available as the [npm usertiming module](https://npmjs.org/package/usertiming). You can install
+using  Node Package Manager (npm):
+
+    npm install usertiming
+
+## Usage
+
+Please see the [W3C UserTiming API Reference](http://www.w3.org/TR/user-timing/) for details on how to use the 
+UserTiming API.
+
+To include the UserTiming.js polyfill, simply include it via a script tag:
+
+```html
+<script type="text/javascript" src="usertiming.min.js"></script>
+```
+
+## Disadvantages of UserTiming.js over native implementations
+
+UserTiming.js provides a 100% functional JavaScript implementation of UserTiming. However, implementing the API in 
+JavaScript has some disadvantages over native (built into the browser) implementations.
+
+1. If the browser does not natively support 
+    [DOMHighResolutionTimestamps / ``window.performance.now()``](http://www.w3.org/TR/hr-time/), UserTiming.js adds a
+    small shim (via the `Date` object) to mock this interface. However, DOMHighResolutionTimestamp provides higher
+    precision (0.1 milliseconds or better) than the native `Date` object can (1.0 millisecond -- or worse in older
+    browsers).  So if `window.performance.now()` has to be mocked, it will not be as precise as native implementations.
+
+2. UserTiming marks and measures are queried via the [PerformanceTimeline](http://www.w3.org/TR/performance-timeline/),
+    for example by using `getEntries()`, `getEntriesByType()` or `getEntriesByName()`.  UserTiming.js adds these 
+    interfaces so you can query for marks and measures, but they obviously will not support any other PerformanceEntrys
+    such as [ResourceTiming](http://www.w3.org/TR/resource-timing/).
+
+3. UserTiming.js is implemented in JavaScript, so it will be less performant than a native implementation.  If you 
+    are calling `mark()` or `measure()` at a high-rate, you might incur a performance cost from the UserTiming.js 
+    JavaScript implementation versus a native implementation.
+
+## Tests
+
+### UserTiming.js tests
+
+UserTiming.js tests are provided in the ``test/`` directory, and can be run via ``nodeunit``:
+
+    nodeunit test/test.js
+
+Or via ``grunt``:
+
+    grunt test
+
+The tests can also be run in a web browser:
+
+    test/test.html
+
+### W3C tests
+
+The latest [W3C UserTiming tests](http://w3c-test.org/webperf/tests/#ut) (as of 2013-04-15) were copied into the 
+``test-w3c/`` directory and can be run in any browser to validate UserTiming.js.  In browsers that natively support 
+UserTiming, UserTiming.js does not change anything so the tests will be running against the native browser interface.
+
+The following changes were made to the W3C test suite to work with UserTiming.js:
+
+* The relative test harness JS/CSS urls were changed to point to the local ``test-w3c/`` directory
+    (such as ``testharness.js``, ``webperftestharness.js``, etc)
+
+* All tests were updated to add a reference to ``../src/usertiming.js`` so usertiming.js is actually used
+
+* ``test_user_timing_measure.htm`` and ``test_user_timing_mark.ht``: The threshold was increased from 20ms to 50ms
+    (due to inefficiencies in the test suite)
+
+Additional notes:
+
+* ``usertiming.js`` does **not pass** the IDL tests (``idlharness.html``), nor will it ever.
+
+* The W3C test harness itself does not appear to work in several older browsers (IE <= 8, Firefox 3.6, etc).  The
+    UserTiming.js [test cases](#Tests) should cover most of what the W3C tests are doing, and the nodeunit test harness
+    works in these older browsers.
+
+## Version History
+
+* v0.0.1 - 2013-04-15: Initial version
diff --git a/deps/nodeunit.css b/deps/nodeunit.css
@@ -0,0 +1,70 @@
+/*!
+ * Styles taken from qunit.css
+ */
+
+h1#nodeunit-header, h1.nodeunit-header {
+    padding: 15px;
+    font-size: large;
+    background-color: #06b;
+    color: white;
+    font-family: 'trebuchet ms', verdana, arial;
+    margin: 0;
+}
+
+h1#nodeunit-header a {
+    color: white;
+}
+
+h2#nodeunit-banner {
+    height: 2em;
+    border-bottom: 1px solid white;
+    background-color: #eee;
+    margin: 0;
+    font-family: 'trebuchet ms', verdana, arial;
+}
+h2#nodeunit-banner.pass {
+    background-color: green;
+}
+h2#nodeunit-banner.fail {
+    background-color: red;
+}
+
+h2#nodeunit-userAgent, h2.nodeunit-userAgent {
+    padding: 10px;
+    background-color: #eee;
+    color: black;
+    margin: 0;
+    font-size: small;
+    font-weight: normal;
+    font-family: 'trebuchet ms', verdana, arial;
+    font-size: 10pt;
+}
+
+div#nodeunit-testrunner-toolbar {
+    background: #eee;
+    border-top: 1px solid black;
+    padding: 10px;
+    font-family: 'trebuchet ms', verdana, arial;
+    margin: 0;
+    font-size: 10pt;
+}
+
+ol#nodeunit-tests {
+    font-family: 'trebuchet ms', verdana, arial;
+    font-size: 10pt;
+}
+ol#nodeunit-tests li strong {
+    cursor:pointer;
+}
+ol#nodeunit-tests .pass {
+    color: green;
+} 
+ol#nodeunit-tests .fail {
+    color: red;
+} 
+
+p#nodeunit-testresult {
+    margin-left: 1em;
+    font-size: 10pt;
+    font-family: 'trebuchet ms', verdana, arial;
+}