{"id":18221673,"url":"https://github.com/pillowpillow/ng2-webstorage","last_synced_at":"2025-05-14T12:10:26.338Z","repository":{"id":8841954,"uuid":"59898075","full_name":"PillowPillow/ng2-webstorage","owner":"PillowPillow","description":"Localstorage and sessionstorage manager - Angular service","archived":false,"fork":false,"pushed_at":"2024-12-11T08:56:19.000Z","size":2745,"stargazers_count":426,"open_issues_count":9,"forks_count":90,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-07T14:42:24.788Z","etag":null,"topics":["angular-service","decorators","localstorage","sessionstorage","web-storage"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/PillowPillow.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-28T14:21:13.000Z","updated_at":"2025-03-21T21:07:08.000Z","dependencies_parsed_at":"2024-06-10T09:29:42.685Z","dependency_job_id":"4aed7c1b-c6fe-4ae1-9e8a-6bd71dfbc9a8","html_url":"https://github.com/PillowPillow/ng2-webstorage","commit_stats":{"total_commits":360,"total_committers":12,"mean_commits":30.0,"dds":"0.10555555555555551","last_synced_commit":"23dfd26c9ce73d018c90042399e7f3f6acb1170c"},"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PillowPillow%2Fng2-webstorage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PillowPillow%2Fng2-webstorage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PillowPillow%2Fng2-webstorage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PillowPillow%2Fng2-webstorage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PillowPillow","download_url":"https://codeload.github.com/PillowPillow/ng2-webstorage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140760,"owners_count":22021219,"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":["angular-service","decorators","localstorage","sessionstorage","web-storage"],"created_at":"2024-11-03T22:03:49.215Z","updated_at":"2025-05-14T12:10:26.310Z","avatar_url":"https://github.com/PillowPillow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ngx-webstorage\n\n### Local and session storage - Angular service\nThis library provides an easy to use service to manage the web storages (local and session) from your Angular application.\nIt provides also two decorators to synchronize the component attributes and the web storages.\n\n[![CircleCI](https://circleci.com/gh/PillowPillow/ng2-webstorage/tree/master.svg?style=svg)](https://circleci.com/gh/PillowPillow/ng2-webstorage/tree/master)\n------------\n\n#### Index:\n* [Getting Started](#gstart)\n    * [Provider Function](#provider_fn)\n* [Services](#services):\n\t* [LocalStorageService](#s_localstorage)\n\t* [SessionStorageService](#s_sessionstorage)\n* [Decorators](#decorators):\n\t* [@LocalStorage](#d_localstorage)\n\t* [@SessionStorage](#d_sessionStorage)\n* [Known issues](#knownissues)\n* [Modify and build](#modifBuild)\n\n------------\n\n### Migrate from v2.x to the v3\n\n1. Update your project to Angular 7+\n2. Rename the module usages by \u003cb\u003eNgxWebstorageModule.forRoot()\u003c/b\u003e *(before: Ng2Webstorage)*\n\u003e The forRoot is now mandatory in the root module even if you don't need to configure the library\n\n\n### Migrate from v13.x to the v18\n\n1. Update your project to Angular 18+\n2. Rename the module usages by \u003cb\u003eprovideNgxWebstorage()\u003c/b\u003e *(before: NgxWebstorageModule.forRoot())*\n3. Add the new provider functions to configure the library\n```typescript\n\tprovideNgxWebstorage(\n\t\twithNgxWebstorageConfig({ separator: ':', caseSensitive: true }),\n\t\twithLocalStorage(),\n\t\twithSessionStorage()\n\t)\n```\n------------\n\n### \u003ca name=\"gstart\"\u003eGetting Started\u003c/a\u003e\n\n1. Download the library using npm `npm install --save ngx-webstorage`\n2. Declare the library in your main module\n\n\t```typescript\n\timport {NgModule} from '@angular/core';\n\timport {BrowserModule} from '@angular/platform-browser';\n\timport {provideNgxWebstorage, withNgxWebstorageConfig} from 'ngx-webstorage';\n\n\t@NgModule({\n\t\tdeclarations: [...],\n\t\timports: [\n\t\t\tBrowserModule\n\t\t],\n\t\tproviders: [\n\t\t\tprovideNgxWebstorage(),\n\t\t\t//provideNgxWebstorage(\n\t\t\t//  withNgxWebstorageConfig({ prefix: 'custom', separator: '.', caseSensitive:true }) \n\t\t\t//)\n\t\t\t// The config allows to configure the prefix, the separator and the caseSensitive option used by the library\n\t\t\t// Default values:\n\t\t\t// prefix: \"ngx-webstorage\"\n\t\t\t// separator: \"|\"\n\t\t\t// caseSensitive: false \n\t\t]\n\t\tbootstrap: [...]\n\t})\n\texport class AppModule {\n\t}\n\n\t```\n\n3. Inject the services you want in your components and/or use the available decorators\n\n\t```typescript\n\timport {Component} from '@angular/core';\n\timport {LocalStorageService, SessionStorageService} from 'ngx-webstorage';\n\n\t@Component({\n\t\tselector: 'foo',\n\t\ttemplate: `foobar`\n\t})\n\texport class FooComponent {\n\n\t\tconstructor(private localSt:LocalStorageService) {}\n\n\t\tngOnInit() {\n\t\t\tthis.localSt.observe('key')\n\t\t\t\t.subscribe((value) =\u003e console.log('new value', value));\n\t\t}\n\n\t}\n\t```\n\n\t```typescript\n\timport {Component} from '@angular/core';\n\timport {LocalStorage, SessionStorage} from 'ngx-webstorage';\n\n\t@Component({\n\t\tselector: 'foo',\n\t\ttemplate: `{{boundValue}}`,\n\t})\n\texport class FooComponent {\n\n\t\t@LocalStorage()\n\t\tpublic boundValue;\n\n\t}\n\t```\n\n### \u003ca name=\"provider_fn\"\u003eProvider Function\u003c/a\u003e\n\nSince the new standalone API and angular v15+, provider functions are now the way to go to configure your application ([learn more](https://angular.dev/reference/migrations/standalone)).\n\n1. From now on to setup your project, you can use the `provideNgxWebstorage` function.\n\n2. You can independently add the (you can of course add them both together):\n   - `localStorage` features with `withLocalStorage`\n   - `sessionStorage` features with `withLocalStorage`\n\n3. You can add a custom configuration with `withNgxWebstorageConfig`\n   \n```ts\nbootstrapApplication(AppComponent, {\n\tproviders: [\n\t\t// ...\n\t\tprovideNgxWebstorage(\n\t\t\twithNgxWebstorageConfig({ separator: ':', caseSensitive: true }),\n\t\t\twithLocalStorage(),\n\t\t\twithSessionStorage()\n\t\t)\n\t]\n})\n```\n\n### \u003ca name=\"services\"\u003eServices\u003c/a\u003e\n--------------------\n\n### \u003ca name=\"s_localstorage\"\u003e`LocalStorageService`\u003c/a\u003e\n\n#### Store( key:`string`, value:`any` ):`void`\n\u003e create or update an item in the local storage\n\n##### Params:\n- **key**:     String.   localStorage key.\n- **value**:     Serializable.   value to store.\n\n##### Usage:\n````typescript\nimport {Component} from '@angular/core';\nimport {LocalStorageService} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `\n\t\t\u003csection\u003e\u003cinput type=\"text\" [(ngModel)]=\"attribute\"/\u003e\u003c/section\u003e\n\t\t\u003csection\u003e\u003cbutton (click)=\"saveValue()\"\u003eSave\u003c/button\u003e\u003c/section\u003e\n\t`,\n})\nexport class FooComponent {\n\n    attribute;\n\n    constructor(private storage:LocalStorageService) {}\n\n    saveValue() {\n      this.storage.store('boundValue', this.attribute);\n    }\n\n}\n````\n\n------------\n\n#### Retrieve( key:`string` ):`any`\n\u003e retrieve a value from the local storage\n\n##### Params:\n- **key**:     String.   localStorage key.\n\n##### Result:\n- Any; value\n\n##### Usage:\n````typescript\nimport {Component} from '@angular/core';\nimport {LocalStorageService} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `\n\t\t\u003csection\u003e{{attribute}}\u003c/section\u003e\n\t\t\u003csection\u003e\u003cbutton (click)=\"retrieveValue()\"\u003eRetrieve\u003c/button\u003e\u003c/section\u003e\n\t`,\n})\nexport class FooComponent {\n\n    attribute;\n\n    constructor(private storage:LocalStorageService) {}\n\n    retrieveValue() {\n      this.attribute = this.storage.retrieve('boundValue');\n    }\n\n}\n````\n\n------------\n\n#### Clear( key?:`string` ):`void`\n\n##### Params:\n- **key**: *(Optional)*     String.   localStorage key.\n\n##### Usage:\n````typescript\nimport {Component} from '@angular/core';\nimport {LocalStorageService, LocalStorage} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `\n\t\t\u003csection\u003e{{boundAttribute}}\u003c/section\u003e\n\t\t\u003csection\u003e\u003cbutton (click)=\"clearItem()\"\u003eClear\u003c/button\u003e\u003c/section\u003e\n\t`,\n})\nexport class FooComponent {\n\n    @LocalStorage('boundValue')\n    boundAttribute;\n\n    constructor(private storage:LocalStorageService) {}\n\n    clearItem() {\n      this.storage.clear('boundValue');\n      //this.storage.clear(); //clear all the managed storage items\n    }\n\n}\n````\n------------\n\n#### IsStorageAvailable():`boolean`\n\n##### Usage:\n````typescript\nimport {Component, OnInit} from '@angular/core';\nimport {LocalStorageService, LocalStorage} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `...`,\n})\nexport class FooComponent implements OnInit {\n\n    @LocalStorage('boundValue')\n    boundAttribute;\n\n    constructor(private storage:LocalStorageService) {}\n\n    ngOnInit() {\n      let isAvailable = this.storage.isStorageAvailable();\n      console.log(isAvailable);\n    }\n\n}\n````\n\n------------\n\n#### Observe( key?:`string` ):`EventEmitter`\n\n##### Params:\n- **key**: *(Optional)*     localStorage key.\n\n##### Result:\n- Observable; instance of EventEmitter\n\n##### Usage:\n````typescript\nimport {Component} from '@angular/core';\nimport {LocalStorageService, LocalStorage} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `{{boundAttribute}}`,\n})\nexport class FooComponent {\n\n    @LocalStorage('boundValue')\n    boundAttribute;\n\n    constructor(private storage:LocalStorageService) {}\n\n    ngOnInit() {\n      this.storage.observe('boundValue')\n        .subscribe((newValue) =\u003e {\n          console.log(newValue);\n        })\n    }\n\n}\n````\n\n\n### \u003ca name=\"s_sessionstorage\"\u003e`SessionStorageService`\u003c/a\u003e\n\u003e The api is identical as the LocalStorageService's\n\n### \u003ca name=\"decorators\"\u003eDecorators\u003c/a\u003e\n--------------------\n\n### \u003ca name=\"d_localstorage\"\u003e`@LocalStorage`\u003c/a\u003e\n\u003e Synchronize the decorated attribute with a given value in the localStorage\n\n#### Params:\n - **storage key**: *(Optional)*    String.   localStorage key, by default the decorator will take the attribute name.\n - **default value**: *(Optional)*    Serializable.   Default value\n\n#### Usage:\n````typescript\nimport {Component} from '@angular/core';\nimport {LocalStorage, SessionStorage} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `{{boundAttribute}}`,\n})\nexport class FooComponent {\n\n\t@LocalStorage()\n\tpublic boundAttribute;\n\n}\n````\n\n------------\n\n### \u003ca name=\"d_sessionStorage\"\u003e`@SessionStorage`\u003c/a\u003e\n\u003e Synchronize the decorated attribute with a given value in the sessionStorage\n\n#### Params:\n - **storage key**: *(Optional)*    String.   SessionStorage key, by default the decorator will take the attribute name.\n - **default value**: *(Optional)*    Serializable.   Default value\n\n#### Usage:\n````typescript\nimport {Component} from '@angular/core';\nimport {LocalStorage, SessionStorage} from 'ngx-webstorage';\n\n@Component({\n\tselector: 'foo',\n\ttemplate: `{{randomName}}`,\n})\nexport class FooComponent {\n\n\t@SessionStorage('AnotherBoundAttribute')\n\tpublic randomName;\n\n}\n````\n\n### \u003ca name=\"knownissues\"\u003eKnown issues\u003c/a\u003e\n--------------------\n\n- *Serialization doesn't work for objects:* \n\nNgxWebstorage's decorators are based upon accessors so the update trigger only on assignation. \nConsequence, if you change the value of a bound object's property the new model will not be store properly. The same thing will happen with a push into a bound array. \nTo handle this cases you have to trigger manually the accessor.\n\n````typescript\nimport {LocalStorage} from 'ngx-webstorage';\n\nclass FooBar {\n\n    @LocalStorage('prop')\n    myArray;\n\n    updateValue() {\n        this.myArray.push('foobar');\n        this.myArray = this.myArray; //does the trick\n    }\n\n}\n````\n\n\n### \u003ca name=\"modifBuild\"\u003eModify and build\u003c/a\u003e\n--------------------\n\n`npm install`\n\n*Start the unit tests:* `npm run test`\n\n*Start the unit tests:* `npm run test:watch`\n\n*Start the dev server:* `npm run dev` then go to *http://localhost:8080/webpack-dev-server/index.html*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpillowpillow%2Fng2-webstorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpillowpillow%2Fng2-webstorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpillowpillow%2Fng2-webstorage/lists"}