Angular decorators to automagically keep variables in HTML5 LocalStorage, SessionStorage, cookies; injectable services for managing and listening to data changes and a bit more.
npm install ngx-storelocalStorage and sessionStorage. It also provides Angular-Injectable Session- and LocalStorageService.@LocalStorage() - to save variable in HTML5 localStorage@SessionStorage() - to save variable in HTML5 sessionStorage@CookieStorage() - to save variable as a cookie@SharedStorage() - to keep variable in temporary memory that can be shared across classes@TempStorage() - alias for SharedStorageLocalStorageService, SessionStorageService, CookiesStorageService and SharedStorageService (read more here)angular2-localstorage (seamless migration)migrateKey decorator config option.forRoot() and .forChild() methods for future use@LocalStorage() @CookieStorage() variable: any; CookieStorage (decorator closer to variable) has higher priority, hence the value will be read from cookies only. The cookie value will be saved in localStorage regardless of its content to keep consistency.WebStorageService.clear('all') - now will remove everything except ngx-store's config (stored in localStorage)WEBSTORAGE_CONFIG@SharedStorage has now alias @TempStorageng add ngx-store. Done!npm i ngx-store --saveapp.module.ts:typescript
import { NgModule } from '@angular/core';
import { WebStorageModule } from 'ngx-store'; @NgModule({
imports: [
WebStorageModule.forRoot(),
],
})
export class AppModule {}
`
Configuration
Things you should take into consideration while configuring this module:
- Decorated objects have added method to easily force save of made changes (configurable by mutateObjects)
- Support for all Array methods that change array object's value can be disabled (configurable by mutateObjects)
- Object mutation can be troublesome for object comparisons, so you can configure this feature for single field passing decorator config
- You may not use prefix (by setting it to ''), however we recommend to use it, as it helps avoid conflicts with other libraries (configurable by prefix)
- There are 3 ways to clear ngx-stored data:
+ 'all' - completely clears current Storage
+ 'prefix' - removes all variables prefixed by ngx-store
+ 'decorators' - removes only variables created by decorating functions (useful when not using prefix)
Default behaviour is specified by setting clearType, but it's possible to pass this parameter directly into service clear() method.
- Examples for cookiesScope can be found in this commentAs this project uses decorating functions, it is important to provide custom configuration in global variable named
NGXSTORE_CONFIG before Angular application load. Here are some ways to do it:
1. Add
2. If you use webpack, you can provide global variable in your file this way:
`javascript
plugins: [
new webpack.DefinePlugin({
NGXSTORE_CONFIG: JSON.stringify({
prefix: '', // etc
})
}),
]
`
Decorators config
Decorating functions can take config object with the following fields:
- - key under the variable will be stored, default key is the variable name
- mutate: boolean - enable or disable object mutation for instance, default depends on global config
- expires: Date - for @CookieStorage() only, specifies expiration date, null = lifetime cookie
- migrateKey: string - previously used key from which the value will be transferred to the current key, the old key will be cleared afterwardsUsage
1. Pretty easy to use decorators. Here is where the real magic happens.
`typescript
import { CookieStorage, LocalStorage, SessionStorage } from 'ngx-store'; export class MySuperComponent {
// it will be stored under ${prefix}viewCounts name
@LocalStorage() viewCounts: number = 0;
// this under name: ${prefix}differentLocalStorageKey
@LocalStorage('differentLocalStorageKey') userName: string = '';
// it will be stored under ${prefix}itWillBeRemovedAfterBrowserClose in session storage
@SessionStorage({key: 'itWillBeRemovedAfterBrowserClose'}) previousUserNames: Array = [];
// it will be read from cookie 'user_id' (can be shared with backend) and saved to localStorage and cookies after change
@LocalStorage() @CookieStorage({prefix: '', key: 'user_id'}) userId: string = '';
// it will be stored in a cookie named ${prefix}user_workspaces for 24 hours
@CookieStorage({key: 'user_workspaces', expires: new Date(new Date().getTime() + 24 60 60 * 1000)}) userWorkspaces = [];
// the value will be transferred from localStorage's "location" key
@LocalStorage({key: 'myLocation', migrateKey: 'location'}) myLocation: string = '';
constructor() {
this.viewCounts++;
this.userName = 'some name stored in localstorage';
this.previousUserNames.push(this.userName);
for (let userName of this.previousUserNames) {
console.log(userName);
}
this.previousUserNames.map(userName => userName.split('').reverse().join(''));
}
}
` Sharing variables across classes: Decorated variables can be easily shared across different classes, e.g. Angular Components (also after their destruction) without need to create new service for this purpose.
typescript
import { LocalStorage, SharedStorage } from 'ngx-store'; export class HomeComponent {
@SharedStorage() title: string = 'Homepage'; // it will be kept in temp memory until app reload
@LocalStorage() userNote: string = 'Leave your note here'; // it will be read from and saved to localStorage
constructor() {
setTimeout(() => {
console.log('userNote:', this.userNote); // it should be changed after user's visit to NestedComponent
}, 5000);
}
}
export class NestedComponent {
@SharedStorage('title') homeTitle: string = '';
@LocalStorage() protected userNote: string = '';
constructor() {
console.log('homeTitle:', this.homeTitle); // should print 'Homepage'
console.log('userNote:', this.userNote); // should print userNote set in HomeComponent
this.userNote = "You've visited NestedComponent!";
}
}
` Force save changes: If you need to modify stored object by not a direct assignment, then you can take advantage of
method to force save made changes. Example:
`typescript
import { CookieStorage, LocalStorage, SessionStorage, WebstorableArray } from 'ngx-store'; export class MySuperComponent {
@LocalStorage() someObject: any = { c: 3 };
@SessionStorage() arrayOfSomethings: WebstorableArray = [0,1,2,3,4];
@CookieStorage({ mutate: false }) someCookie: {version?: number, content?: string} = {};
constructor() {
this.someObject.a = 1;
this.someObject['b'] = 2;
delete this.someObject['c'];
for (let i = 0; i < this.arrayOfSomethings.length; i++) {
this.arrayOfSomethings[i] += i;
}
this.someCookie.version++;
this.someCookie.content = 'please save me';
// upper changes won't be saved without the lines below
this.someObject.save();
this.arrayOfSomethings.save();
this.someCookie = this.someCookie; // it looks weird, but also will do the job even without object mutation
}
}
` Limited lifecycle classes in AoT compilation: There is a special case when Service or Component in your application containing decorated variable is being destroyed:
typescript
import { OnDestroy } from '@angular/core';
import { LocalStorage } from 'ngx-store'; export class SomeService implements OnDestroy { // implement the interface
@LocalStorage() destroyedVariable: any = {};
ngOnDestroy() {} // event empty method is needed to allow ngx-store handle class destruction
}
`2. Use the services to manage your data:
typescript
import { CookiesStorageService, LocalStorageService, SessionStorageService, SharedStorageService } from 'ngx-store'; export class MyService {
constructor(
localStorageService: LocalStorageService,
sessionStorageService: SessionStorageService,
cookiesStorageService: CookiesStorageService,
sharedStorageService: SharedStorageService,
) {
console.log('all cookies:');
cookiesStorageService.utility.forEach((value, key) => console.log(key + '=', value));
}
public saveSomeData(object: Object, array: Array) {
this.localStorageService.set('someObject', object);
this.sessionStorageService.set('someArray', array);
this.localStorageService.keys.forEach((key) => {
console.log(key + ' =', this.localStorageService.get(key));
});
}
public clearSomeData(): void {
this.localStorageService.clear('decorators'); // removes only variables created by decorating functions
this.localStorageService.clear('prefix'); // removes variables starting with set prefix (including decorators)
this.sessionStorageService.clear('all'); // removes all session storage data
}
}
`Note: Always define default value at the property you are using decorator.
Note: Never use
loop on decorated Arrays without filtering by .hasOwnProperty()`.Note: Please don't ngx-store circular structures as this library uses JSON.stringify to encode data before saving.
Note: When you change prefix from '' (empty string) old values won't be removed automatically to avoid deleting necessary data. You should handle it manually or set clearType to 'all' for some time.
Contributions are welcome!