local.redis.docs.js | |
---|---|
| |
Redis-like API for HTML5 Local Storage | |
Created by: Joel Kemp and Eudis Duran | |
License: MIT. | |
Downloads | |
| |
Notes | |
Polyfill for IE8Since IE8 does not support HTML5 Local Storage, a cookie-based polyfill is supplied to facilitate the basic web storage API. | |
Datatype support | |
Local Redis can handle non-string input to the commands. Hence, it is possible to store and retrieve objects, arrays, numbers, and literal strings. This is achieved internally via JSON stringify and parse. | localRedis.set('foo', 'bar');
localRedis.set(4, 'bar');
localRedis.set({username: "Joel Kemp"}, {post: "Hello"});
localRedis.set(['foo', 3, {username: "Joel Kemp"}], [1, 2, 3]);
localRedis.set(null, null); |
Argument assertions | |
The commands will throw an error if they are given an incorrect number of arguments. Note the usage section of each command to see the accepted number of arguments. | |
Event Firing on Storage Update | |
The library emits a | |
If you want to visualize the changes being made to the datastore, you can listen for the fired event and act appropriately. | |
If your project utilizes jQuery, then the library will use jQuery's
event-firing functionality. Otherwise, we fire events via the
(IE-specific) | |
Local Storage API | |
| localRedis.setItem('foo', 'bar');
localRedis.getItem('foo');
localRedis.key(0);
localRedis.clear();
localRedis.removeItem('foo'); |
Note: Key stringifying and parsing are not done on the above methods.
Please use | |
These functions also emit the storage events. | |
Keys API | |
delUsage: | |
Removes the specified key(s). Returns the number of keys removed. | localRedis.set('foo', 'bar');
localRedis.set('bar', 'foobar');
localRedis.del('foo', 'bar'); // Returns 2 |
Side effects: Clears existing expirations on keys, if set. | |
existsUsage: | |
Determines whether or not the passed key exists in storage.
Returns | localRedis.set({foo: 'bar'}, 'bar');
localRedis.exists({foo: 'bar'}); // Returns 1
localRedis.exists('foo'); // Returns 0
localRedis.exists(1234); // Returns 0 |
renameUsage: | |
Renames | |
Side effects: Transfers the | localRedis.set('foo', 'foobar');
localRedis.expire('foo', 2);
localRedis.rename('foo', 'bar');
localRedis.get('bar'); // Returns 'foobar'
localRedis.get('foo'); // Returns null
localRedis.expires('bar'); // Returns 1 |
Throws if | |
renamenxUsage: | |
Renames | localRedis.set('foo', 'bar');
localRedis.renamenx('foo', 'foobar'); // Returns 1
localRedis.get('foobar'); // Returns 'bar' |
Side effects: Same as | |
Throws under the same conditions as | |
getkeyUsage: | |
Retrieves the first key associated with | localRedis.set('foo', 'bar');
localRedis.set('bar', 'bar');
localRedis.getkey('bar'); // Returns 'foo'
localRedis.getkey('bar', true); // Returns ['foo', 'bar'] |
Note: This is a custom, non-Redis function. | |
expireUsage: | |
Expires | localRedis.set('foo', 'bar');
localRedis.expire('foo', 2); // Returns 1
localRedis.expire('bar', 1.5); // Returns 0 |
Read more about the expiration algorithm. | |
pexpireUsage: | |
Expires | localRedis.set('foo', 'bar');
localRedis.set('bar', 'bar');
localRedis.pexpire('foo', 500); // Returns 1
localRedis.pexpire('bar', 10); // Returns 1 |
expiresUsage: | |
Determines whether or not | localRedis.set('foo', 'bar');
localRedis.expire('foo', 2);
localRedis.expires('foo'); // Returns 1 |
Note: This is a custom, non-Redis function. | |
expireatUsage: | |
Expires a key at the supplied, second-based UNIX timestamp.
This is useful for expiring the key at a particular date.
Returns | localRedis.set('foo', 'bar');
localRedis.expireat('foo', 1348517858.724); // Returns 1 |
Throws if the timestamp has already passed. | |
pexpireatUsage: | |
Similar to | localRedis.set('foo', 'bar');
localRedis.pexpireat('foo', 1348517858724); // Returns 1
localRedis.pexpireat('foobar'); // Returns 0 |
Throws if the timestamp has already passed. | |
persistUsage: | |
Removes the | localRedis.set('foo', 'bar');
localRedis.expire('foo', 2);
localRedis.persist('foo'); // Returns 1
localRedis.persist('foobar'); // Returns 0 |
ttlUsage: | |
Returns the time-to-live (in seconds) of a key, or | localRedis.set('foo', 'bar');
localRedis.expire('foo', 2);
localRedis.ttl('foo'); // Returns 2
localRedis.ttl('foobar'); // Returns -1 |
pttlUsage: | |
Similar to | localRedis.set('foo', 'bar');
localRedis.expire('foo', 2);
localRedis.pttl('foo'); // Returns a few ms less than 2000
localRedis.pttl('foobar'); // Returns -1 |
randomkeyUsage: | |
Returns a random key from storage or | localRedis.randomkey(); // Returns null
localRedis.set('foo', 'bar');
localRedis.set('bar', 'foobar');
localRedis.set('car', 'foo');
localRedis.randomkey(); // Returns one of the keys |
keysUsage: | |
Finds all keys that match the (regular expression) pattern.
Returns a list of keys or a single key that matches | localRedis.set('foo', 'bar');
localRedis.set('bar', 'bar');
localRedis.set('car', 'bar');
localRedis.keys('ar'); // Returns ['bar', 'car']
localRedis.keys('fo*'); // Returns 'foo' |
Strings API | |
getUsage: | |
Retrieves the value associated with | localRedis.set('foo', 'bar');
localRedis.set('id', 404);
localRedis.get('foo'); // Returns 'bar'
localRedis.get('id'); // Returns 404 |
Note: If the key is set with the value of null, then | localRedis.set('foo', null);
localRedis.get('foo'); // Returns null which looks like 'foo' does not exist
localRedis.exists('foo'); // Returns 1; hence, 'foo' does exist but has a null value |
setUsage: | |
Stores the | localRedis.set('foo', 'bar');
localRedis.set(4, 232);
localRedis.set({foo: 'name'}, 'bar').set('foobar', 'bar');
localRedis.set('bar', [1, 2, 3, 4, 5]); |
Note: This method deviates from the status | |
Side effects: Resets/refreshes | |
Throws if the set exceeds the quota for localStorage (i.e., throws if localStorage is full). | |
getsetUsage: | |
Sets the | localRedis.set('foo', 'bar');
localRedis.getset('foo', 'foobar'); // Returns 'bar'
localRedis.get('foo'); // Returns 'foobar' |
Side effects: Resets/refreshes | |
mgetUsage: | |
Retrieves the value for each passed key. Returns a list of values where the index of each value in the list corresponds to the index of the key in the parameter list or array. | localRedis.set('foo', 'bar');
localRedis.set('bar', 'foobar');
localRedis.mget('foo', 'bar'); // Returns ['bar', 'foobar'] |
msetUsage: | |
Sets up multiple | localRedis.mset('foo', 'bar', 'bar', 'foobar');
localRedis.mget('foo', 'bar'); // Returns ['bar', 'foobar'] |
Note: a missing value will get the value | |
Side effects: None. Unlike | |
setnxUsage: | |
Sets up the | localRedis.setnx('foo', 'bar'); // Returns 1
localRedis.setnx('foo', 'foobar'); // Returns 0
localRedis.get('foo'); // Returns 'bar' |
Side effects: None, since the key shouldn't exist, and hence, wouldn't have an expiration. | |
msetnxUsage: | |
Sets up the | localRedis.msetnx('foo', 'bar', 'bar', 'foobar'); // Returns 1
localRedis.msetnx('foo', 'foobar'); // Returns 0 |
incrUsage: | |
Increments the key by 1 or sets it to 1 if the key does not exist. | localRedis.incr('hits');
localRedis.get('hits'); // Returns 1 |
Throws if the value of | |
| |
Side effects: None. | |
Note: If | |
incrbyUsage: | |
Increments the key by amount or sets the key to amount if it doesn't exist. | localRedis.incrby('foo', 4);
localRedis.get('foo'); // Returns 4 |
Throws if the value of | |
| |
Side effects: None. | |
Note: If | |
mincrUsage: | |
Increments multiple keys by 1 or sets a key to 1 if it does not exist. | localRedis.mincr('foo', 'bar');
localRedis.mget('foo', 'bar'); // Returns [1, 1] |
Throws under the same conditions as | |
mincrbyUsage: | |
Increments multiple keys by amount or sets a key to amount if it does not exist. | localRedis.mincrby('foo', 3, 'bar', 4);
localRedis.mincrby(['id', 4, 'hits', 1]);
localRedis.mget('foo', 'bar', 'id', 'hits'); // Returns [3, 4, 4, 1] |
Note: This is a custom, non-Redis function. | |
Throws under the same conditions as | |
decrUsage: | |
Decrements a key by | localRedis.set('foo', 1);
localRedis.decr('foo'); // Returns 0
localRedis.decr('bar'); // Returns -1 |
Throws under the same conditions as | |
decrUsage: | |
Decrements the key by 1 or sets it to -1 if the key does not exist. | localRedis.decr('hits');
localRedis.get('hits'); // Returns -1 |
Throws if the value of | |
| |
Side effects: None. | |
Note: If | |
decrbyUsage: | |
Decrements the key by amount or sets the key to amount if it doesn't exist. | localRedis.decrby('foo', 4);
localRedis.get('foo'); // Returns 4 |
Throws if the value of | |
| |
Side effects: None. | |
Note: If | |
mdecrUsage: | |
Decrements multiple keys by 1 or sets a key to -1 if it does not exist. | localRedis.mdecr('foo', 'bar');
localRedis.mget('foo', 'bar'); // Returns [-1, -1] |
Throws under the same conditions as | |
mdecrbyUsage: | |
Decrement multiple keys by amount or sets a key to | localRedis.mdecrby('foo', 3, 'bar', 4);
localRedis.mdecrby(['id', 4, 'hits', 1]);
localRedis.mget('foo', 'bar', 'id', 'hits'); // Returns [-3, -4, -4, -1] |
Note: This is a custom, non-Redis function. | |
Throws under the same conditions as | |
appendUsage: | |
Appends | localRedis.set('foo', 'bar');
localRedis.append('foo', 'car'); // Returns 6
localRedis.get('foo'); // Returns 'barcar'
localRedis.append('bar', 'car'); // Returns 3 |
strlenUsage: | |
Retrieves the length of | localRedis.set('foo', 'bar');
localRedis.strlen('foo'); // Returns 3
localRedis.strlen('bar'); // Returns 0 |
Throws if the value is not a string. | |
setexUsage: | |
Sets the | localRedis.setex('foo', 10, 'bar'); // Expires 'foo' in 10s |
Note: This is equivalent to running a | |
Throws if | |
psetexUsage: | |
Similar to | localRedis.psetex('foo', 10, 'bar'); // Expires 'foo' in 10 milliseconds |
Throws if | |
Lists API | |
lpushUsage: | |
Inserts all of the values at the head of the list stored at | localRedis.set('foo', [1, 2, 3]);
localRedis.lpush('foo', 4, 5, 6); // Returns 6
localRedis.get('foo'); // Returns [6, 5, 4, 1, 2, 3] |
Note: Adds the values outward in. So the values | |
Throws if the existing value stored at | |
lpushxUsage: | |
Inserts values at the head of the list value stored at | localRedis.set('foo', [1, 2, 3]);
localRedis.lpushx('foo', 4, 5, 6); // Returns 6
localRedis.get('foo'); // Returns [6, 5, 4, 1, 2, 3]
localRedis.lpushx('bar', 3); // Returns 0 |
rpushUsage: | |
Inserts/appends all of the values at the tail of the list stored at | localRedis.set('foo', [1, 2, 3]);
localRedis.rpush('foo', 4, 5, 6); // Returns 6
localRedis.get('foo'); // Returns [1, 2, 3, 4, 5, 6] |
Throws if the existing value stored at | |
rpushxUsage: | |
Inserts values at the tail of the list value stored at | localRedis.set('foo', [1, 2, 3]);
localRedis.rpushx('foo', 4, 5, 6); // Returns 6
localRedis.get('foo'); // Returns [1, 2, 3, 4, 5, 6]
localRedis.rpushx('bar', 3); // Returns 0 |
llenUsage: | |
Retrieves the length of the list value stored at | localRedis.set('foo', [1, 2, 3]);
localRedis.llen('foo'); // Returns 3
localRedis.llen('bar'); // Returns 0 |
Throws if the value at | |
lrangeUsage: 'lrange(key, start, stop)' | |
Retrieves the specified elements (indexed by start and stop)
of the list at key.
Returns a list of the retrieved elements or the empty list
if | localRedis.set('foo', [1, 2, 3]);
localRedis.lrange('foo', 0, 1); // Returns [1, 2]
localRedis.lrange('foo', -3, -1); // Returns [1, 2, 3] |
Note: The values for start and stop can be negative – indexing from the end of the list. | |
lremUsage: | |
Removes the first count ocurrences of value in the list
stored at key.
Returns the number of removed elements or | |
| localRedis.set('foo', [1, 1, 2, 1]);
localRedis.lrem('foo', 2, 1);
localRedis.get('foo'); // Returns [2, 1] |
| localRedis.set('foo', [1, 1, 2, 1]);
localRedis.lrem('foo', -1, 1);
localRedis.get('foo'); // Returns [1, 1, 2] |
| localRedis.set('foo', [1, 1, 2, 1]);
localRedis.lrem('foo', 0, 1);
localRedis.get('foo'); // Returns [2] |
Throws when the value at | |
lpopUsage: | |
Removes and returns the first element from the list stored at key.
Or | localRedis.set('foo', [1, 2, 3]);
localRedis.lpop('foo'); // Returns 1
localRedis.get('foo'); // Returns [2, 3] |
Throws when the value at | |
rpopUsage: | |
Removes and returns the last element from the list stored at key.
Or | localRedis.set('foo', [1, 2, 3]);
localRedis.rpop('foo'); // Returns 3
localRedis.get('foo'); // Returns [1, 2] |
Throws when the value at | |
linsertUsage: | |
Stores the | localRedis.set('foo', [1, 2, 3]);
localRedis.linsert('foo', 'before', 2, 15);
localRedis.get('foo'); // Returns [1, 15, 2, 3]
localRedis.linsert('foo', 'after', 15, 5);
localRedis.get('foo'); // Returns [1, 15, 5, 2, 3] |
Throws if the reference is not 'before' or 'after'. | |