{"id":13527909,"url":"https://github.com/gsklee/ngStorage","last_synced_at":"2025-04-01T10:33:00.732Z","repository":{"id":57741846,"uuid":"11212142","full_name":"gsklee/ngStorage","owner":"gsklee","description":"localStorage and sessionStorage done right for AngularJS.","archived":false,"fork":false,"pushed_at":"2018-09-17T17:31:07.000Z","size":138,"stargazers_count":2326,"open_issues_count":77,"forks_count":461,"subscribers_count":55,"default_branch":"master","last_synced_at":"2025-03-29T20:33:57.857Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gsklee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-06T02:54:54.000Z","updated_at":"2025-03-21T09:21:43.000Z","dependencies_parsed_at":"2022-09-10T22:31:54.684Z","dependency_job_id":null,"html_url":"https://github.com/gsklee/ngStorage","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsklee%2FngStorage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsklee%2FngStorage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsklee%2FngStorage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsklee%2FngStorage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gsklee","download_url":"https://codeload.github.com/gsklee/ngStorage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246625786,"owners_count":20807823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:02:06.136Z","updated_at":"2025-04-01T10:33:00.404Z","avatar_url":"https://github.com/gsklee.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","awesome-web-storage [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)","Storage","others"],"sub_categories":["Different Storage APIs"],"readme":"ngStorage\n=========\n\n[![Build Status](https://travis-ci.org/gsklee/ngStorage.svg)](https://travis-ci.org/gsklee/ngStorage)\n[![Dependency Status](https://david-dm.org/gsklee/ngStorage.svg)](https://david-dm.org/gsklee/ngStorage)\n[![devDependency Status](https://david-dm.org/gsklee/ngStorage/dev-status.svg)](https://david-dm.org/gsklee/ngStorage#info=devDependencies)\n\nAn [AngularJS](https://github.com/angular/angular.js) module that makes Web Storage working in the *Angular Way*. Contains two services: `$localStorage` and `$sessionStorage`.\n\n### Differences with Other Implementations\n\n* **No Getter 'n' Setter Bullshit** - Right from AngularJS homepage: \"Unlike other frameworks, there is no need to [...] wrap the model in accessors methods. Just plain old JavaScript here.\" Now you can enjoy the same benefit while achieving data persistence with Web Storage.\n\n* **sessionStorage** - We got this often-overlooked buddy covered.\n\n* **Cleanly-Authored Code** - Written in the *Angular Way*, well-structured with testability in mind.\n\n* **No Cookie Fallback** - With Web Storage being [readily available](http://caniuse.com/namevalue-storage) in [all the browsers AngularJS officially supports](http://docs.angularjs.org/misc/faq#canidownloadthesourcebuildandhosttheangularjsenvironmentlocally), such fallback is largely redundant.\n\nInstall\n=======\n\n### Bower\n\n```bash\nbower install ngstorage\n```\n\n*NOTE:* We are `ngstorage` and *NOT* `ngStorage`. The casing is important!\n\n### NPM\n```bash\nnpm install ngstorage\n```\n\n*NOTE:* We are `ngstorage` and *NOT* `ngStorage`. The casing is important!\n\n### nuget\n\n```bash\nInstall-Package gsklee.ngStorage\n```\n\nOr search for `Angular ngStorage` in the nuget package manager. \u003chttps://www.nuget.org/packages/gsklee.ngStorage\u003e\n\nCDN\n===\n\n### cdnjs\ncdnjs now hosts ngStorage at \u003chttps://cdnjs.com/libraries/ngStorage\u003e\n\nTo use it\n\n``` html\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/ngStorage/0.3.10/ngStorage.min.js\"\u003e\u003c/script\u003e\n```\n\n### jsDelivr\n\njsDelivr hosts ngStorage at \u003chttp://www.jsdelivr.com/#!ngstorage\u003e\n\nTo use is\n\n``` html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/ngstorage@0.3.11/ngStorage.min.js\"\u003e\u003c/script\u003e\n```\n\nUsage\n=====\n\n### Require ngStorage and Inject the Services\n\n```javascript\nangular.module('app', [\n    'ngStorage'\n]).controller('Ctrl', function(\n    $scope,\n    $localStorage,\n    $sessionStorage\n){});\n```\n\n### Read and Write | [Demo](http://plnkr.co/edit/3vfRkvG7R9DgQxtWbGHz?p=preview)\n\nPass `$localStorage` (or `$sessionStorage`) by reference to a hook under `$scope` in plain ol' JavaScript:\n\n```javascript\n$scope.$storage = $localStorage;\n```\n\nAnd use it like you-already-know:\n\n```html\n\u003cbody ng-controller=\"Ctrl\"\u003e\n    \u003cbutton ng-click=\"$storage.counter = $storage.counter + 1\"\u003e{{$storage.counter}}\u003c/button\u003e\n\u003c/body\u003e\n```\n\n\u003e Optionally, specify default values using the `$default()` method:\n\u003e\n\u003e ```javascript\n\u003e $scope.$storage = $localStorage.$default({\n\u003e     counter: 42\n\u003e });\n\u003e ```\n\nWith this setup, changes will be automatically sync'd between `$scope.$storage`, `$localStorage`, and localStorage - even across different browser tabs!\n\n### Read and Write Alternative (Not Recommended) | [Demo](http://plnkr.co/edit/9ZmkzRkYzS3iZkG8J5IK?p=preview)\n\nIf you're not fond of the presence of `$scope.$storage`, you can always use watchers:\n\n```javascript\n$scope.counter = $localStorage.counter || 42;\n\n$scope.$watch('counter', function() {\n    $localStorage.counter = $scope.counter;\n});\n\n$scope.$watch(function() {\n    return angular.toJson($localStorage);\n}, function() {\n    $scope.counter = $localStorage.counter;\n});\n```\n\nThis, however, is not the way ngStorage is designed to be used with. As can be easily seen by comparing the demos, this approach is way more verbose, and may have potential performance implications as the values being watched quickly grow.\n\n### Delete | [Demo](http://plnkr.co/edit/o4w3VGqmp8opfrWzvsJy?p=preview)\n\nPlain ol' JavaScript again, what else could you better expect?\n\n```javascript\n// Both will do\ndelete $scope.$storage.counter;\ndelete $localStorage.counter;\n```\n\nThis will delete the corresponding entry inside the Web Storage.\n\n### Delete Everything | [Demo](http://plnkr.co/edit/YiG28KTFdkeFXskolZqs?p=preview)\n\nIf you wish to clear the Storage in one go, use the `$reset()` method:\n\n```javascript\n$localStorage.$reset();\n````\n\n\u003e Optionally, pass in an object you'd like the Storage to reset to:\n\u003e\n\u003e ```javascript\n\u003e $localStorage.$reset({\n\u003e     counter: 42\n\u003e });\n\u003e ```\n\n### Permitted Values | [Demo](http://plnkr.co/edit/n0acYLdhk3AeZmPOGY9Z?p=preview)\n\nYou can store anything except those [not supported by JSON](http://www.json.org/js.html):\n\n* `Infinity`, `NaN` - Will be replaced with `null`.\n* `undefined`, Function - Will be removed.\n\n### Usage from config phase\n\nTo read and set values during the Angular config phase use the `.get/.set`\nfunctions provided by the provider.\n\n```javascript\nvar app = angular.module('app', ['ngStorage'])\n.config(['$localStorageProvider',\n    function ($localStorageProvider) {\n        $localStorageProvider.get('MyKey');\n\n        $localStorageProvider.set('MyKey', { k: 'value' });\n    }]);\n```\n\n### Prefix\n\nTo change the prefix used by ngStorage use the provider function `setKeyPrefix`\nduring the config phase.\n\n```javascript\nvar app = angular.module('app', ['ngStorage'])\n.config(['$localStorageProvider',\n    function ($localStorageProvider) {\n        $localStorageProvider.setKeyPrefix('NewPrefix');\n    }])\n```\n\n### Custom serialization\n\nTo change how ngStorage serializes and deserializes values (uses JSON by default) you can use your own functions.\n\n```javascript\nangular.module('app', ['ngStorage'])\n.config(['$localStorageProvider', \n  function ($localStorageProvider) {\n    var mySerializer = function (value) {\n      // Do what you want with the value.\n      return value;\n    };\n    \n    var myDeserializer = function (value) {\n      return value;\n    };\n\n    $localStorageProvider.setSerializer(mySerializer);\n    $localStorageProvider.setDeserializer(myDeserializer);\n  }];)\n```\n\n### Minification\nJust run `$ npm install` to install dependencies.  Then run `$ grunt` for minification.\n\n### Hints\n\n#### Watch the watch\n\nngStorage internally uses an Angular watch to monitor changes to the `$storage`/`$localStorage` objects. That means that a digest cycle is required to persist your new values into the browser local storage.\nNormally this is not a problem, but, for example, if you launch a new window after saving a value...\n\n```javascript\n$scope.$storage.school = theSchool;\n$log.debug(\"launching \" + url);\nvar myWindow = $window.open(\"\", \"_self\");\nmyWindow.document.write(response.data);\n```\n\nthe new values will not reliably be saved into the browser local storage. Allow a digest cycle to occur by using a zero-value `$timeout` as:\n\n```javascript\n$scope.$storage.school = theSchool;\n$log.debug(\"launching and saving the new value\" + url);\n$timeout(function(){\n   var myWindow = $window.open(\"\", \"_self\");\n   myWindow.document.write(response.data);\n});\n```\n\nor better using `$scope.$evalAsync` as:\n\n```javascript\n$scope.$storage.school = theSchool;\n$log.debug(\"launching and saving the new value\" + url);\n$scope.$evalAsync(function(){\n   var myWindow = $window.open(\"\", \"_self\");\n   myWindow.document.write(response.data);\n});\n```\n\nAnd your new values will be persisted correctly.\n\nTodos\n=====\n\n* ngdoc Documentation\n* Namespace Support\n* Unit Tests\n* Grunt Tasks\n\nAny contribution will be appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsklee%2FngStorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgsklee%2FngStorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsklee%2FngStorage/lists"}