angular-typed-storage

[Deprecated]

It was unnecessarily heavy and restrictive to wrap this library up as an Angular module. Please use the unwrapped version, here: typed-storage.

New Usage

With Angular's dependency injection, the new usage looks like this:

import { TypedStorageService, typedStorageFactory, TypedStorageKey } from 'typed-storage';

@NgModule({
  // ...
  providers: [
    <FactoryProvider>{ provide: TypedStorageService, useFactory: typedStorageFactory },
    // ...
  ]
})
export class AppModule {

TypedStorage

The Angular 2 & 4 TypedStorage module provides an easy way to store and retrieve nested view models from browser storage (either localStorage or sessionStorage).

What it is not

In some browsers, such as Internet Explorer, it cannot be a drop-in replacement for localStorage or sessionStorage when using property- or dictionary-style references (as opposed to .getItem()/.setItem). The specific Javascript feature we use for this is the Proxy class. See Mozilla's notes on browser support for the Proxy class), for more information.

Will work:

localStorage["mykey"] = 653;
// browser refresh...
let someValue = localStorage["mykey"];
// someValue == "314"

Will also work:

typedStorage.setItem("mykey", 653);
// browser refresh...
let someValue = typedStorage.getItem("mykey");
// someValue == "314"

Will only work in modern browsers:

typedStorage["mykey"] = 653;
// browser refresh...
let someValue = typedStorage["mykey"];
// someValue == undefined

Features

• It implements the Storage interface:

let s: Storage = localStorage;
s = sessionStorage;
s = typedStorage;

• Allows optional namespacing in the underlying storage provider to avoid key collisions with other modules used by your application.
• Can use either string keys or instances of TypedStorageKey for better type safety.

Usage

// This presumes TypedStorage was configured with namespace com.example.myapp and localStorage:
let myKey = new TypedStorageKey(MyClass, "myInst");
let myInst: MyClass = new MyClass();
typedStorage.setItem(myKey, myInst);
typedStorage[myKey] = myInst; // property access will only work in modern browsers.
// localStorage now contains key "com.example.myapp.myInst" with a JSON-serialized representation of myInst.

// ...

myInst = typedStorage.getItem(myKey);
// or
myInst = typedStorage[myKey];
typedStorage.removeItem(myKey);

View Models

We use SimpleMapper to recursively map deserialized objects back into their original view models. Nested models that you want mapped should use SimpleMapper's @mappable attribute.

export class MyWidget {
    Id: number = 0;
    Name: string = null;
    get Display(): string { 
        return `${Name} (Id: ${Id})`;
    }

    @mappable(MyWidget)
    Wiggy: MyWidget = null;
}

Note: Each property must have a default value, otherwise SimpleMapper will not be able to detect the property at run-time. The Typescript, Id: number; (with no default value) compiles to return Javascript's undefined at run-time. Not even the property key will exist in the compiled Javascript.

Installation

Run npm install --save-dev angular-typed-storage inside of an Angular 4 project.

Setup

Inside your application's app.module.ts file, make the following additions.

// ...
import { TypedStorageModule } from 'angular-typed-storage';

// ...
import * as vm from './view-models'; // optional, if using VM refs instead of name strings.

@NgModule({
    declarations: [
        // ...
    ],
    providers: [
        { provide: TypedStorageLoggerToken, useValue: console /* or a logger matching console's sig */ }
    ],
    imports: [
        // ...
        TypedStorageModule.forRoot({ns: "com.example.app", storage: localStorage })
    ]
})
export class AppModule {
    constructor() {

Options

let config: IConfig = {
    /** Deprecated. This defaults to console. Please use TypedStorageLoggerToken in your providers, instead. */
    logger: undefined,

    /** The namespace to use, i.e., com.example.myapp. Default: null = do not use namespace. */
    ns: "com.example.myapp",

    /** The dictionary of view models to use for recursive mapping, if any. Default: empty.*/
    viewModels: {},

    /**
     * Whether or not to use Proxy to facilitate indexer access to typed storage, i.e., typedStorage[myprop] == typedStorage.getItem(myprop).
     * Proxy does not exist in some older browsers like Internet Explorer. Default: false.
     */
    noProxy: false,

    /** Underlying storage: either localStorage or sessionStorage. Default: localStorage. */
    storage: localStorage,
}

The view models would all be exported via index.ts "Barrels" (see Angular glossary):

export * from './user-view-model.ts';
export * from './cat-view-model.ts';
// ...

And in your classes, import like this:

import { TypedStorageService, TypedStorageKey } from 'angular-typed-storage';

export class MyService {
  private userKey: TypedStorageKey<UserViewModel> = new TypedStorageKey(UserViewModel, "user");

  constructor(private typedStorage: TypedStorageService) {
  // ...
  }

  ngOnInit() {
      doSomething(this.typedStorage.getItem(userKey));
  }
}

Build

Run npm run build to build the project. The build artifacts will be stored in the dist/ directory.

Running unit tests

Run npm test to execute the unit tests via Karma.

Code coverage

While running tests, code coverage will be available at ./coverage/chrome/html/index.html.

Documentation

Run 'npm run compodoc' to generate documentation. Then run 'npm run compodoc-serve' to see auto-generated documentation and documentation coverage on port 8080.

Further help

Feel free to post issues.