Nancy's Preferred Machete

    ngx-webstorage
    TypeScript icon, indicating that this package has built-in type declarations

    10.0.1 • Public • Published

    ngx-webstorage

    Local and session storage - Angular service

    This library provides an easy to use service to manage the web storages (local and session) from your Angular application. It provides also two decorators to synchronize the component attributes and the web storages.


    Index:


    Migrate from v2.x to the v3

    1. Update your project to Angular 7+
    2. Rename the module usages by NgxWebstorageModule.forRoot() (before: Ng2Webstorage)

    The forRoot is now mandatory in the root module even if you don't need to configure the library


    Getting Started

    1. Download the library using npm npm install --save ngx-webstorage

    2. Declare the library in your main module

      import {NgModule} from '@angular/core';
      import {BrowserModule} from '@angular/platform-browser';
      import {NgxWebstorageModule} from 'ngx-webstorage';
      
      @NgModule({
      	declarations: [...],
      	imports: [
      		BrowserModule,
      		NgxWebstorageModule.forRoot(),
      		//NgxWebstorageModule.forRoot({ prefix: 'custom', separator: '.', caseSensitive:true }) 
      		// The forRoot method allows to configure the prefix, the separator and the caseSensitive option used by the library
      		// Default values:
      		// prefix: "ngx-webstorage"
      		// separator: "|"
      		// caseSensitive: false
      	],
      	bootstrap: [...]
      })
      export class AppModule {
      }
    3. Inject the services you want in your components and/or use the available decorators

      import {Component} from '@angular/core';
      import {LocalStorageService, SessionStorageService} from 'ngx-webstorage';
      
      @Component({
      	selector: 'foo',
      	template: `foobar`
      })
      export class FooComponent {
      
      	constructor(private localSt:LocalStorageService) {}
      
      	ngOnInit() {
      		this.localSt.observe('key')
      			.subscribe((value) => console.log('new value', value));
      	}
      
      }
      import {Component} from '@angular/core';
      import {LocalStorage, SessionStorage} from 'ngx-webstorage';
      
      @Component({
      	selector: 'foo',
      	template: `{{boundValue}}`,
      })
      export class FooComponent {
      
      	@LocalStorage()
      	public boundValue;
      
      }

    Services


    LocalStorageService

    Store( key:string, value:any ):void

    create or update an item in the local storage

    Params:
    • key: String. localStorage key.
    • value: Serializable. value to store.
    Usage:
    import {Component} from '@angular/core';
    import {LocalStorageService} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `
    		<section><input type="text" [(ngModel)]="attribute"/></section>
    		<section><button (click)="saveValue()">Save</button></section>
    	`,
    })
    export class FooComponent {
    
        attribute;
    
        constructor(private storage:LocalStorageService) {}
    
        saveValue() {
          this.storage.store('boundValue', this.attribute);
        }
    
    }

    Retrieve( key:string ):any

    retrieve a value from the local storage

    Params:
    • key: String. localStorage key.
    Result:
    • Any; value
    Usage:
    import {Component} from '@angular/core';
    import {LocalStorageService} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `
    		<section>{{attribute}}</section>
    		<section><button (click)="retrieveValue()">Retrieve</button></section>
    	`,
    })
    export class FooComponent {
    
        attribute;
    
        constructor(private storage:LocalStorageService) {}
    
        retrieveValue() {
          this.attribute = this.storage.retrieve('boundValue');
        }
    
    }

    Clear( key?:string ):void

    Params:
    • key: (Optional) String. localStorage key.
    Usage:
    import {Component} from '@angular/core';
    import {LocalStorageService, LocalStorage} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `
    		<section>{{boundAttribute}}</section>
    		<section><button (click)="clearItem()">Clear</button></section>
    	`,
    })
    export class FooComponent {
    
        @LocalStorage('boundValue')
        boundAttribute;
    
        constructor(private storage:LocalStorageService) {}
    
        clearItem() {
          this.storage.clear('boundValue');
          //this.storage.clear(); //clear all the managed storage items
        }
    
    }

    IsStorageAvailable():boolean

    Usage:
    import {Component, OnInit} from '@angular/core';
    import {LocalStorageService, LocalStorage} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `...`,
    })
    export class FooComponent implements OnInit {
    
        @LocalStorage('boundValue')
        boundAttribute;
    
        constructor(private storage:LocalStorageService) {}
    
        ngOnInit() {
          let isAvailable = this.storage.isStorageAvailable();
          console.log(isAvailable);
        }
    
    }

    Observe( key?:string ):EventEmitter

    Params:
    • key: (Optional) localStorage key.
    Result:
    • Observable; instance of EventEmitter
    Usage:
    import {Component} from '@angular/core';
    import {LocalStorageService, LocalStorage} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `{{boundAttribute}}`,
    })
    export class FooComponent {
    
        @LocalStorage('boundValue')
        boundAttribute;
    
        constructor(private storage:LocalStorageService) {}
    
        ngOnInit() {
          this.storage.observe('boundValue')
            .subscribe((newValue) => {
              console.log(newValue);
            })
        }
    
    }

    SessionStorageService

    The api is identical as the LocalStorageService's

    Decorators


    @LocalStorage

    Synchronize the decorated attribute with a given value in the localStorage

    Params:

    • storage key: (Optional) String. localStorage key, by default the decorator will take the attribute name.
    • default value: (Optional) Serializable. Default value

    Usage:

    import {Component} from '@angular/core';
    import {LocalStorage, SessionStorage} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `{{boundAttribute}}`,
    })
    export class FooComponent {
    
    	@LocalStorage()
    	public boundAttribute;
    
    }

    @SessionStorage

    Synchronize the decorated attribute with a given value in the sessionStorage

    Params:

    • storage key: (Optional) String. SessionStorage key, by default the decorator will take the attribute name.
    • default value: (Optional) Serializable. Default value

    Usage:

    import {Component} from '@angular/core';
    import {LocalStorage, SessionStorage} from 'ngx-webstorage';
    
    @Component({
    	selector: 'foo',
    	template: `{{randomName}}`,
    })
    export class FooComponent {
    
    	@SessionStorage('AnotherBoundAttribute')
    	public randomName;
    
    }

    Known issues


    • Serialization doesn't work for objects:

    NgxWebstorage's decorators are based upon accessors so the update trigger only on assignation. Consequence, 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. To handle this cases you have to trigger manually the accessor.

    import {LocalStorage} from 'ngx-webstorage';
    
    class FooBar {
    
        @LocalStorage('prop')
        myArray;
    
        updateValue() {
            this.myArray.push('foobar');
            this.myArray = this.myArray; //does the trick
        }
    
    }

    Modify and build


    npm install

    Start the unit tests: npm run test

    Start the unit tests: npm run test:watch

    Start the dev server: npm run dev then go to http://localhost:8080/webpack-dev-server/index.html

    Install

    npm i ngx-webstorage

    DownloadsWeekly Downloads

    43,631

    Version

    10.0.1

    License

    MIT

    Unpacked Size

    246 kB

    Total Files

    64

    Last publish

    Collaborators

    • polochon