Browser Storage

Browser_Storage.js, a client side JavaScript wrapper for localStorage and document.cookie interactions.

Check the gh-pages branch for source files of live demo hosted by GitHub Pages, development tips for your first Pull Request, and Continuous Integration configurations for automated tests.

The following covers how to install this branch as a submodule within your own project, notes for private hosting, and methods that Browser_Storage.js currently has defined as of late .

---

Table of Contents

• ⬆ Top of ReadMe File

• ⚡ Quick Start

  • 📝 Edit Your ReadMe File
  • 🕸 Edit Your HTML
  • 💾 Commit and Push

• 📜 Browser_Storage.js References

• 🗒 Notes

• 📇 Attribution

• ©️ License

---

Quick Start

Bash Variables

_module_https_url='https://github.com/javascript-utilities/browser-storage.git'
_module_relative_path='assets/javascript/modules/browser-storage'

Git Commands

cd "<your-git-project-path>"

git checkout gh-pages
git submodule add -b master --name browser-storage "${_module_https_url}" "${_module_relative_path}"

git submodule update
cd "${_module_relative_path}"
git checkout master
git pull

Version Locking; recommended for those that audit every dependency...

git checkout tags/<tag_name> -b <branch_name>

... replace <tag_name> with the tag to checkout and <branch_name> with a custom name, eg...

git checkout tags/v0.0.1 -b loc-v0.0.1

Edit Your ReadMe File

Quick Start Section

Clone with the following to avoid incomplete downloads



    git clone --recurse-submodules <url-for-your-project>

Updates/Upgrades Section

Update/upgrade submodules via


    git submodule update --init --recursive
    git submodule update --merge

Edit Your HTML

<script src="assets/javascript/modules/browser-storage/browser-storage.js"
        type="text/javascript"></script>


<script type="text/javascript">
  const storage = new Browser_Storage();

  if (!storage.storage_available) {
    throw new Error('No storage available!');
  }

  storage.setItem('test__string', 'Spam!', 3);
  if (storage.getItem('test__string') !== 'Spam!') {
    throw new Error('Storage cannot be relied upon!')
  }

  console.log(':tada: Browser Storage seems to be available!');
</script>

Test that things work!

Open a web browser pointing at the server hosting the above changes and try interacting with the Browser_Storage() instance...

storage.setItem('something', true, 3);
console.log("storage.getItem('something') -> " + storage.getItem('something'));

storage.setItem('another-thing', {first: true}, 3);
const another_thing = storage.getItem('another-thing');
console.log('another_thing -> ' + another_thing);

Commit and Push

git add .gitmodules
git add assets/javascript/modules/browser-storage
git add README.md


git commit -F- <<'EOF'
:heavy_plus_sign: Adds javascript-utilities/browser-storage dependency


**Edits**


- `README.md` file, documentation updates for submodules


**Additions**

- `.gitmodules` file, tracks other Git repository code utilized by this project

- `assets/javascript/modules/browser-storage` submodule, Git tracked dependency
EOF


git push origin gh-pages

🎉 Excellent 🎉 your site is now ready to begin unitizing the storage instance within other JavaScript projects!

---

Browser Storage References

Properties

• supports_cookies contains boolean, cookies support

• supports_local_storage contains boolean, support for localStorage

• storage_available contains boolean, storage supported during initialization

Methods

• supportsLocalStorage(), returns boolean, availability of localStorage support

• supportsCookies(), returns boolean, availability of cookies support

• constructorRefresh() returns boolean, a copy of constructor() that may be called after initialization to refresh class properties

• getItem(key), returns undefined or value of any valid JSON associated with passed key

• removeItem(key), returns boolean after removing values associated with passed key

• setItem(key, value, days_to_live), associates key with value for a number of days_to_live

• keys() returns Array, that may point to stored values

• clear() returns boolean, after removing all locally stored values from browser storage

Iterator Example

for (let stored of storage) {
  console.log(stored.key + ' -> ' stored.value);
}

---

Notes

The getItem() method returns undefined for undefined values, avoid setting keys to "undefined" to avoid confusion.

Note, if/when this Browser Storage falls-back to using cookies both removeItem(key) and clear() methods require a page refresh to also remove stored key names. Additionally by default each request from browsers that use cookies as a fall-back will send cookies unless the server sends Set-Cookies to request that the browser will stop-it, eg...

server {
    listen 80;
    server_name static.example.com;
    root /var/www/example.com;

    fastcgi_hide_header Set-Cookie;
}

... as suggested by jesin on DigitalOcean or search for cookie-free domain along with the server name in question.

When Browser_Storage is using localStorage then set's days_to_live is currently meaningless.

Opening new Issues is supper! However, to avoid attention fragmentation be certain to search for related Issues that could be added to instead. Developers please clone to a separate directory, then checkout the gh-pages branch which tracks the master branch as a submodule, and prior to issuing a Pull Request check the Community for any relevant updates.

---

Attribution

• StackOverflow

  • node.js - Creating instance of a class directly from require
  • How to describe “object” arguments in jsdoc?
  • What is the shortest function for reading a cookie by name in JavaScript?
  • How to make an iterator out of an ES6 class
  • JavaScript navigator.cookieEnabled Browser Compatibility

• JestJS

  • Getting Started
  • expect(...)tothrowerror

• JSDoc

  • Getting Started

• GitHub Gists

  • check-if-cookies-are-enabled.js

• W3 Schools

  • JavaScript Cookies

---

License

Browser Storage submodule quick start documentation for Git tracked web sites
Copyright (C) 2019  S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation; version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
by `jesin`
on