All About Key Values

Key values are stored in code.org's Firebase API. They are universal and accessible by any instance of a project. However, they are not copied when a project is remixed.

Basic recap on key value syntax:

var data = {"some_data":1234}; // can also be a string or number or array
var key = "some_key"; // must be a string
setKeyValue(key,data,function() {
  console.log("success"); // value successfully stored
},function(e) {
  throw e; // value failed to be stored
});

getKeyValue(key,function(d) {
  console.log(d); // should print what was in the data variable
},function(e) {
  throw e; // value failed to be fetched
});

Keys:

• Must be a string (other data types throw an error: "e.replace is not a function")
• Must not be empty (won't save, KEY_INVALID callback error)
• String must be < 698 chars long (won't save, empty callback error)
• String must not contain some characters:
  • "$", "#", "[", "]", and "/" (will save under different key (all characters replaced by a "-"), KEY_RENAMED callback error)
  • "\n", "\t", "\b", "\r", and other things (won't save, KEY_INVALID callback error)
  • Fix by using encodeURIComponent(key) before getting/setting key values

Values:

• Can be any data type
• Objects cannot contain cyclical references (data.data = data will throw: "Maximum call stack size exceeded")
• JSON.stringify(data).length <= 4096 (otherwise callback error "The value is too large. The maximum allowable size is 4096 bytes.")
• Saving more than 2 levels deep causes some information to be lost and converted to undefined
  • {a:1,r:{b:2,r:{d:3}}} will save as {a:1,r:{b:2,r:{d:undefined}}};
  • [1,[2,[3]]] will save as [1,[2,[undefined]]];
  • Fix by using JSON.stringify(data) before setting the key value and JSON.parse(retrived_data) when getting the key value.

My advanced key value functions:

function getBigKeyValue(key,callback,failure) {
  key = encodeURIComponent(key);
  var value = "";
  var n = 0;
  var getNext = function() {
    getKeyValue(key+"+"+n,function(part){
      if (!part) {
        if (value === "") {
          callback();
          return;
        }
        try {
          value = JSON.parse(value);
          callback(value);
        } catch(e) {
          if (typeof failure == 'function') failure(e);
          else throw e;
        }
        return;
      }
      value += part;
      n++;
      getNext();
    },function(e){
      if (typeof failure == 'function') failure(e);
      else throw e;
    });
  };
  getNext();
}
function setBigKeyValue(key,value,success,failure) {
  key = encodeURIComponent(key);
  value = JSON.stringify(JSON.stringify(value));
  value = value.substring(1,value.length-1);
  var n = 0;
  function setNext() {
    var x = 4094;
    if (value[4093] == "\\") x--;
    var part = value.substring(0,x);
    part = JSON.parse('"'+part+'"');
    value = value.substring(x);
    if (part.length == 0) {
      if (typeof success == 'function') success();
      return;
    }
    setKeyValue(key+"+"+n,part,setNext,function(e){
      if (typeof failure == 'function') failure(e);
      else throw e;
    });
    n++;
  }
  setNext();
}

Please note, that the above functions are very slow, so use the regular setKeyValue/getKeyValue when you can.
These functions should allow you to store data of any length/depth under keys of any name.

Additionally, when changing key values, use something similar to this:

function updateKeyValue(key,callback,failure) {
  getKeyValue(key,function(v){
    v = callback(v);
    if (!v) return;
    setKeyValue(key,v,function(){},failure);
  },failure);
}

It helps prevent overwrites. However, be careful about using prompt() inside the callback.