TypedStorage
A wrapper for Storage implementations (local or session) that provides an easy way to store and retrieve strongly-typed, nested models.
Basic Usage
; // typed;typedStorage.setItemmyKey, myClassInstance;// ... browser refresh ...;
Features
- Optionally namespaced storage keys
- When so configured,
ts.getItem(aKey)
can translate tostorage.getItem("com.example.myPrimKey");
- When so configured,
- Implements the Storage interface, so the API is a superset of browser storage
- Deserializes nested models via a configurable mapper
- We use SimpleMapper for mapping, but you are free to provide your own mapper implementation during initialization.
- Understands native types:
ts.setItem("loggedIn", new Date())
followed byts.getItem("loggedIn")
will retrieve a Date object.
What it is not (anti-features)
While getItem and setItem are available in all browsers, dictionary-style references, like typedStorage['key']
,
are unavailable in some older browsers such as Internet Explorer (but not Edge), for example. In such browsers,
typedStorage cannot be a drop-in replacement for localStorage or sessionStorage, which
allow such references.
The specific browser feature we use is the Proxy class. See Mozilla's notes on browser support for the Proxy class, for more information.
What works in all browsers
typedStorage.setItem"keyOne", 653; // untyped ; // typed;typedStorage.setItemmyKey, myClassInstance; // ... browser refresh ... ; // untyped;// someValue == "653"// noTwo == myClassInstancetypedStorage.clear;typedStorage.removeItemmyKey; // redundant after clear()
browsers that implement the Proxy class
What works intypedStorage = 653; // browser refresh... ;// someValue == undefined
Model Mapping
We use SimpleMapper to recursively map deserialized objects back into their original models. Nested models should use SimpleMapper's @mappable attribute, if you want them to be recursively mapped.
You can also implement the map()
method on the IMapper
interface (below) to supply your own Or, you can wrap a 3rd-party mapper library.
Each destination 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. In that case, not even the property key would exist in the compiled Javascript.
Custom Model Mapper
If you are going to implement a custom model mapper, you only need to implement IMapper and supply that during configuration.
Installation
npm install --save-dev typed-storage
Setup and Options
;; // Use the factory, if you want to use the Proxy interface.;
And in your classes, use it like this:
;;;
Building from source and contributing
Contributions are welcome. Please follow good code quality conventions.
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
or npm run cover
to execute the unit tests or tests + coverage.
Code coverage
While running tests, code coverage will be available at /[path/to/repo]/coverage/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.