{"_id":"asyncStorage","_rev":"5-ada1151109d0f2eb3e281a1c95269f5d","name":"asyncStorage","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"asyncStorage","version":"0.1.0","main":"./build/asyncStorage.js","_npmUser":{"name":"WebReflection","email":"andrea.giammarchi@gmail.com"},"_id":"asyncStorage@0.1.0","dependencies":{},"devDependencies":{},"optionalDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.24","_nodeVersion":"v0.6.19","_defaultsLoaded":true,"dist":{"shasum":"c217ae8d276824134a747c0cbc441ac901717120","tarball":"https://registry.npmjs.org/asyncStorage/-/asyncStorage-0.1.0.tgz","integrity":"sha512-k0hRGjVW9kgvCiHTVzDJGNKd9XS5gg5xcCgAL1KpnT79/nqT0V7/xjcS5hLqloTG9X+pFVuw94AhQijudagYag==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIGgMrIUtV4Hioeyk4OGl2EkKTU80sx3BskV68/OLXLnyAiBRtO3IkTj7VIQDJx1Wsbt0DcuQqHOzsJr2ItluQn5/qg=="}]},"maintainers":[{"name":"WebReflection","email":"andrea.giammarchi@gmail.com"}]}},"readme":"asyncStorage :: a developer friendly Asynchronous Storage\n=========================================================\nlet's face reality, the status of storages in the Web is a mess.\nlocalStorage is a synchronous API not suitable at all to store data.\nWebSQL has been abandoned, still the only option, as non experimental, in Safari, Chrome, and Opera.\nFirefox is trying to support IndexedDB which right now is the most messed up API ever: loads of inconsistencies across platforms, included different versions of Firefox itself.\nInternet Explorer 10, the one not even out yet, has insignificant market sharing 'till now.\nMy proposal to bring WebSQL back through Firefox extension has been banned, after approval, due potential securities issues ... so, what the hell we have to do in order to use a proper storage that is not ultra-complicated to understand, learn, and use?\n\nThe Problem with the WebStorage API\n-----------------------------------\n**localStorage** and **sessionStorage** have been around for quite a while and many developers are using these for any sort of task, including any sort of data stored in these synchronous storage without considering that:\n\n  * **your data is not safe**, the first script that will easily perform a `localStorage.clear()` in the page your script is, your whole logic will magically fuck up without any notification (also because the event \"storage\" is completely randomly implemented)\n  * **synchronous means blocking**, but we all agree that synchronous logic is easier to implement and maintain, right? ... well, unless you are not storing a few bytes once a while, you are making the browser potentially stuck ... just stop it, if you find this solution convenient\n  * **your data is limited**, from 2mb up to 5mb but most important, the WebStorage API does not provide any way to know how much data is still available\n  * **you are doing it wrong** ... and please don't judge me for this sentence, the problem is that 99% of online tutorials on `localStorage` are using direct property access, completely obtrusive for any sort of shimmable solution **you** would like to implement, plus 99% of the time these tutorials are not using a `try{}catch(e){}` statement around every single `localStorage.setItem(key, value)` call, which means your business logic is already broken\n\nA Solution Based On WebStorage API\n----------------------------------\nWhat if you have nothing new to learn, using exactly the same API the WebStorage offer, except how to handle callbacks?\nThis is what is this project about, a basically identical API borrowed directly from the Web Storage one, with a couple of extra arguments per each *asynchronous* method such *callback* and *errorback*, where both are even optional.\n\nThe Concept\n-----------\nFirst of all, the main purpose of this project is to use any asynchronous possibility available in the browser through a **key/value pairs** based interface where **both keys and values should be strings**.\nIt is not the purpose of this script to provide any *JSON* shim in your code, but of course as you have probably used *JSON* already to store data in a generic storage, you can do the same with this implementation, remembering to `JSON.stringify(yourDataObject)` before you store it.\nBack to the asynchronous concept, Where there is no possibility, the `localStorage` or even `document.cookie` is used as fallback so that even IE6 should work \"_without problems_\", whenever you decided to harakiri supporting latter browser.\nThe very first option, if available, is the **WebSQL** storage, the best thing ever destroyed by *W3C*, the most cross platform, for both Desktop and Mobile, storage possibility.\n**IndexedDB** would be the other option where WebSQL is not available. This order might change in the future preferring IndexedDB as first option.\nAll others will fallback into *localStorage* or *document.cookie* and I am not discarding at all the possibility to use a *SharedObject* from the Flash Player world ... but, you know, I have abandoned Flash Player about 6 years ago and if I can make it without it, now that would be cool!\nWhat else? Oh well, it's easy!\n\nSo you made the localStorage asynchronous? Tell me how easier it is ...\n-----------------------------------------------------------------------\n\n    asyncStorage.create(\"myDBName\", function (db, numberOfEntries) {\n        // database created, time to rock'n'roll!\n        var callback = function (value, key) {\n            if (value === \"true\") {\n                // do amazing stuff for the very first time\n            }\n            // do whatever you want to\n        };\n        // check how many values you have stored so far\n        if (numberOfEntries === 0) {\n            // add some default entry\n            db.setItem(\"neverLoaded\", \"true\", callback);\n        } else {\n            db.setItem(\"neverLoaded\", \"false\", callback);\n        }\n    });\n\nAbove is just an example of _easiness_ provided by this asynchronousStorage but here few main pros:\n\n  * **unobtrusive**, you chose your own database name as you would do for any of your _libraries or namespaces_ . This simply means something like `localStorage.clear()`, performed by another library, will not erase your whole data. `db.clear()` aim is to clean only data **you** stored and nobody else.\n  * **asynchronous**, since almost every method is made with async in mind. The only two things that are not asynchronous are `db.length` and, since length is synchronous, `db.key(index)` to retrieve the `key` associated to that index.\n  * **nothing new to learn** which is the most annoying part of all these _not fully defined yet_ options we have today in the Web scenario\n\nAsynchronousStorage API\n-----------------------\n  * `create(name, callback)` creates a new database with specific name in order to, somehow, simulate namespaces in the storage itself. `callback(db, numberOfEntries)` will be fired once the database has been created.\n  * `create(name, callback, errorback)` does the same, except you might want to handle potential errors during database creation (user denied, not enough space, etc).\n  * `create(name, callback, errorback, size)` does the same, except you might want to specify in advance the size of the database. This overload works as expected with WebSQL only.\n  * `db.setItem(key, value[, callback[, errorback]])` set an item in the storage and calls `callback(value, key, db)` once the operation is completed. The `errorback` is called if something went wrong during this operation.\n  * `db.getItem(key[, callback[, errorback]])` retrieves a value from the storage, `callback(value, key, db)` is called once the operation is completed where the `value` is exactly `null` wherever `key` was not set before\n  * `db.removeItem(key[, callback[, errorback]])` remove an item from the storage, calls `callback(key, db)` once succeeded\n  * `db.clear([callback[, errorback]])` remove all keys associated to your **database name**, the one used to create the storage at the very beginning. `callback(db, numberOfEntries)` will be triggered once the operation has been completed, same signature of the storage creation for functions reusability.\n  * `db.key(index)` returns **synchronously** the associated key for that index. This is necessary to make easier for developers loops over all keys as they do already with the localStorage, i.e.\n\n        function isItLastOne() {\n            if (!--i) {\n                doAgainAllStuff();\n            }\n        }\n        for (var i = 0; i < db.length; i++) {\n            db.removeItem(db.key(i), isItLastOne);\n        }\n\n  * `db.length` returns the length of all stored keys **in your database name**\n  * `db.name` returns the name you chose for this storage instance\n  * `db.type` returns the type of the database you are using such _WebSQL_, _IndexedDB_ (not yet), _localStorage_, and _cookie_\n\nAnd this is pretty much it ... wanna test? [this page should be green](http://www.3site.eu/db/test/ \"test\")\n\nTODOs\n-----\n  * improve tests to test errorbacks too\n  * optionally, consider a fifth fallback through Flash Player shared object (*meh...!*)","maintainers":[{"name":"WebReflection","email":"andrea.giammarchi@gmail.com"}],"time":{"modified":"2022-06-13T03:38:39.800Z","created":"2012-06-08T14:15:51.905Z","0.1.0":"2012-06-08T14:15:54.989Z"}}