Bug 921202 Adding docs, making default definition for Objects only, a…

…nd using memoize

doc/module-source/sdk/ui/id.md

@@ -0,0 +1,42 @@
+<!-- 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/. -->
+
+The `ui/id` module provides the `identify` helper method for creating
+and defining UI component IDs.
+
+<api name="identify">
+@function
+Makes and/or gets a unique ID for the input.
+
+Making an ID
+
+    const { identify } = require('sdk/ui/id');
+
+    const Thingy = Class({
+      initialize: function(details) {
+        let id = identify(this);
+      }
+    });
+
+Getting an ID
+
+    const { identify } = require('sdk/ui/id');
+    const { Thingy } = require('./thingy');
+
+    let thing = Thingy(/* ... */);
+    let thingID = identify(thing);
+
+Defining ID generator
+
+    const { identify } = require('sdk/ui/id');
+
+    const Thingy = Class(/* ... */);
+
+    identify.define(Thingy, thing => thing.guid);
+
+@param object {Object}
+  Object to create an ID for.
+@returns {String}
+  Returns a UUID by default (or domain specific ID based on a provided definition).
+</api>

lib/sdk/ui/id.js

@@ -10,18 +10,18 @@ module.metadata = {
 const method = require('method/core');
 const { uuid } = require('../util/uuid');
 
-const identified = new WeakMap();
+// NOTE: use lang/functional memoize when it is updated to use WeakMap
+function memoize(f) {
+  const memo = new WeakMap();
 
-let identify = method('identify');
-identify.define(function(thing) {
-  if (!thing) {
-    return uuid();
-  }
-
-  if (!identified.has(thing)) {
-    identified.set(thing, uuid());
-  }
+  return function memoizer(o) {
+    let key = o;
+    if (!memo.has(key))
+      memo.set(key, f.apply(this, arguments));
+    return memo.get(key);
+  };
+}
 
-  return identified.get(thing);
-});
+let identify = method('identify');
+identify.define(Object, memoize(function() { return uuid(); }));
 exports.identify = identify;

test/test-ui-id.js

@@ -9,13 +9,13 @@ const { Class } = require('sdk/core/heritage');
 const signature = /{[0-9a-f\-]+}/;
 
 exports['test generate id'] = function(assert) {
-  let first = identify();
+  let first = identify({});
   let second = identify({});
 
   assert.ok(signature.test(first), 'first id has a correct signature');
   assert.ok(signature.test(second), 'second id has a correct signature');
 
-  assert.notEqual(first, identify(), 'identify generated new uuid [1]');
+  assert.notEqual(first, identify({}), 'identify generated new uuid [1]');
   assert.notEqual(first, second, 'identify generated new uuid [2]');
 };