Skip to content

Commit

Permalink
Moved UMD module definition to build process.
Browse files Browse the repository at this point in the history
This makes it easier to bundle MemoryStorage with your own code using e.g. Browserify or Webpack.
Also added some tests to make sure loading from AMD loaders is working.
  • Loading branch information
Download committed Sep 14, 2015
1 parent ac2d418 commit 5438389
Show file tree
Hide file tree
Showing 17 changed files with 476 additions and 213 deletions.
40 changes: 34 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# memorystorage <sub><sup>v0.9.7</sup></sub>
# memorystorage <sub><sup>v0.9.8</sup></sub>
Memory-backed storage that implements the [Web Storage API](http://www.w3.org/TR/webstorage/), making it a drop-in replacement for `localStorage` and `sessionStorage` in environments where these are not available.
[Project website](http://download.github.io/memorystorage)

## Download
* [memorystorage.js](https://cdn.rawgit.com/download/memorystorage/0.9.7/src/memorystorage.js) (~3kB, commented)
* [memorystorage.min.js](https://cdn.rawgit.com/download/memorystorage/0.9.7/dist/memorystorage.min.js) (~2kB, minified)
* [memorystorage.min.js.map](https://cdn.rawgit.com/download/memorystorage/0.9.7/dist/memorystorage.min.js.map) (~2kB, debug map file)
* [memorystorage.umd.js](https://cdn.rawgit.com/download/memorystorage/0.9.8/src/memorystorage.umd.js) (~4kB, commented)
* [memorystorage.min.js](https://cdn.rawgit.com/download/memorystorage/0.9.8/dist/memorystorage.min.js) (~2kB, minified)
* [memorystorage.min.js.map](https://cdn.rawgit.com/download/memorystorage/0.9.8/dist/memorystorage.min.js.map) (~2kB, debug map file)

## Include on your page
`memorystorage` can be used directly from CDN, or from a local script file.
`memorystorage` can be used directly from CDN, from a local script file, or from a module loader.

### CDN
This is by far the easiest method and gives good performance to boost. Use this if you are in doubt.
```xml
<script src="https://cdn.rawgit.com/download/memorystorage/0.9.7/dist/memorystorage.min.js"></script>
<script src="https://cdn.rawgit.com/download/memorystorage/0.9.8/dist/memorystorage.min.js"></script>
```

### Local script file
Expand All @@ -21,6 +22,33 @@ Download memorystorage.min.js, place it in a folder `lib` in the root of your we
<script src="lib/memorystorage.min.js"></script>
```

### Module loaders
Memorystorage implements the Universal Module Pattern and as such, is available to be consumed
from Node modules as well as via an AMD loader such as RequireJS.

#### Node
```javascript
var MemoryStorage = require('memorystorage');
// here, the MemoryStorage function is available
var myStorage = new MemoryStorage('my-app');
```

#### AMD
```javascript
define(['memorystorage'], function(MemoryStorage){
// here, the MemoryStorage function is available
var myStorage = new MemoryStorage('my-app');
});
```
To be able to load MemoryStorage from CDN as an AMD module, configure the CDN url like so <small>(note the absence of `.js` in the url)</small>:
```javascript
require.config({
paths: {
'memorystorage': 'https://cdn.rawgit.com/download/memorystorage/0.9.8/dist/memorystorage.min'
}
});
```

## Create a memory storage object
The `MemoryStorage` function creates (or returns) a storage object implementing the W3C Web Storage API.
By default, scripts share a `global` storage object, so scripts can access and mutate each other's store
Expand Down
4 changes: 2 additions & 2 deletions dist/memorystorage.min.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion dist/memorystorage.min.js.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

102 changes: 102 additions & 0 deletions dist/memorystorage.umd.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
(function (u, m, d) {
if (typeof define === 'function' && define.amd) {define('memorystorage', [], function(){return (d());});}
else if (typeof exports === 'object') {module.exports = d();}
else {u[m] = d();}
}(this, 'MemoryStorage', function() {'use strict';

/*!
* memorystorage.js - A memory-backed implementation of the Web Storage API.
*
* @copyright Copyright 2015 by Stijn de Witt. Some rights reserved.
* @license Licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
*/
// API methods and properties will be cloaked
var API = {'clear':1, 'getItem':1, 'id':1, 'key':1, 'length':1, 'removeItem':1, 'setItem':1},
API_LENGTH = Object.keys(API).length,
CLOAK = '__memorystorage_cloaked_items__';

// Used to store all memorystorage objects
var storage = {};

/** @module memorystorage */

/**
* Creates a new MemoryStorage object implementing the <a href="http://www.w3.org/TR/webstorage/">Web Storage API</a> using memory.
*
* <p>If no arguments are given, the created memory storage object will read from and write to the
* <code>global</code> memory storage. If a string argument is given, the new storage object
* will read from and write to it's own segment of memory. Any data written to such a memory
* storage object will only show up in other memory storage objects that have been created with
* the same id. This data will not show up in the <code>global</code> memory space. As such it
* is recommended to always construct a memory storage object with a unique string id as argument.</p>
*
* @param id Optional string argument used to isolate this memory storage object from others.
*
* @alias module:memorystorage.MemoryStorage
* @class
*/
function MemoryStorage(id) {// jshint ignore:line
// make sure id is assigned
id = id || 'global';
// try to get existing store
var result = storage[id];
// return it if found
if (result) {return result;}

// make sure there is no harm in leaving out new in invocations to MemoryStorage
if (! (this instanceof MemoryStorage)) {return new MemoryStorage(id);}

// create a new store and save a ref to it so we can get it back later
result = storage[id] = this;
// create a space to store 'cloaked' key/values: items that have a key
// that collides with Web Storage API method names.
var cloaked = {};
Object.defineProperty(result, CLOAK, {
enumerable: false,
get: function(){return cloaked;}
});
// Allow client code to read the id
Object.defineProperty(result, 'id', {
enumerable: true,
get: function(){return id;}
});
// Create the length property
Object.defineProperty(result, 'length', {
enumerable: true,
get: function(){
return Object.keys(this).length + Object.keys(this[CLOAK]).length - API_LENGTH;
}
});
// Create API methods
result.getItem = function MemoryStorage_getItem(key) {
return key in API ? this[CLOAK][key] : this[key];
};
result.setItem = function MemoryStorage_setItem(key, val) {
if (key in API) {this[CLOAK][key] = val;}
else {this[key] = val;}
};
result.removeItem = function MemoryStorage_removeItem(key) {
if (key in API) {delete this[CLOAK][key];}
else {delete this[key];}
};
result.key = function MemoryStorage_key(idx) {
var keys = Object.keys(this).concat(Object.keys(this[CLOAK]));
keys = keys.filter(function(x){return !(x in API);});
return idx >= 0 && idx < keys.length ? keys[idx] : null;
};
result.clear = function MemoryStorage_clear() {
var keys = Object.keys(this).filter(function(x){return !(x in API);});
for (var i=0,key; key=keys[i]; i++) {
if (! (key in API)) {delete this[key];}
}
keys = Object.keys(this[CLOAK]);
for (var i=0,key; key=keys[i]; i++) {
delete this[CLOAK][key];
}
};
return result;
}


return MemoryStorage;
}));
2 changes: 1 addition & 1 deletion doc/classes.list.html
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ <h3 class="subsection-title">Classes</h3>

<span class="jsdoc-message">
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.2</a>
on Wed Sep 2nd 2015 using the <a
on Mon Sep 14th 2015 using the <a
href="https://github.com/terryweiss/docstrap">DocStrap template</a>.
</span>
</footer>
Expand Down
2 changes: 1 addition & 1 deletion doc/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ <h1 class="page-title">Index</h1>

<span class="jsdoc-message">
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.2</a>
on Wed Sep 2nd 2015 using the <a
on Mon Sep 14th 2015 using the <a
href="https://github.com/terryweiss/docstrap">DocStrap template</a>.
</span>
</footer>
Expand Down
Loading

0 comments on commit 5438389

Please sign in to comment.