Bug 724428 - provide uuid parsing from uuid module

packages/api-utils/docs/uuid.md

@@ -0,0 +1,27 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+Module `uuid` provides low level API for generating / parsing UUID, that may
+be necessary when hacking on internals of the platform.
+
+
+## Generate UUID
+
+Module exports `uuid` function. When called without arguments it will uses
+platform-specific methods to obtain a `nsID` that can be considered to be
+globally unique.
+
+    let uuid = require('api-utils/uuid').uuid()
+
+## Parsing UUID
+
+Sometimes one might need to create `nsID` from an existing UUID string. Same
+`uuid` function may be used to parse such UUID strings into an `nsID`:
+
+    let { uuid } = require('api-utils/uuid');
+    let firefoxUUID = uuid('{ec8030f7-c20a-464f-9b0e-13a3a9e97384}');
+
+For more details about UUID representations and what they are used for by the
+platform see MDN documentation for
+[JSID](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIJSID)

packages/api-utils/lib/uuid.js

@@ -1,45 +1,13 @@
-/* vim:set ts=2 sw=2 sts=2 et: */
-/* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is Jetpack.
- *
- * The Initial Developer of the Original Code is
- * the Mozilla Foundation.
- * Portions created by the Initial Developer are Copyright (C) 2011
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *   Irakli Gozalishvili <gozala@mozilla.com> (Original Author)
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 "use strict";
 
-const { Cc, Ci } = require('chrome');
+const { Cc, Ci, components: { ID: parseUUID } } = require('chrome');
+const { generateUUID } = Cc['@mozilla.org/uuid-generator;1'].
+                          getService(Ci.nsIUUIDGenerator);
 
-exports.uuid = Cc['@mozilla.org/uuid-generator;1'].
-               getService(Ci.nsIUUIDGenerator).
-               generateUUID;
+// Returns `uuid`. If `id` is passed then it's parsed to `uuid` and returned
+// if not then new one is generated.
+exports.uuid = function uuid(id) id ? parseUUID(id) : generateUUID()

packages/api-utils/tests/test-uuid.js

@@ -2,7 +2,7 @@
 
 const { uuid } = require('api-utils/uuid');
 
-exports['test uuid'] = function(assert) {
+exports['test generate uuid'] = function(assert) {
   let signature = /{[0-9a-f\-]+}/
   let first = String(uuid());
   let second = String(uuid());
@@ -12,4 +12,12 @@ exports['test uuid'] = function(assert) {
   assert.notEqual(first, second, 'guid generates new guid on each call');
 };
 
+exports['test parse uuid'] = function(assert) {
+  let firefoxUUID = '{ec8030f7-c20a-464f-9b0e-13a3a9e97384}';
+  let actual = uuid(firefoxUUID);
+
+  assert.equal(actual.number, firefoxUUID, 'uuid parsed given string');
+  assert.equal(String(actual), firefoxUUID, 'serializes to the same value');
+};
+
 require('test').run(exports);