@ngx-cache/core  

Cache utility for Angular


> Please support this project by simply putting a Github star. Share this library with friends on Twitter and everywhere else you can.

Table of contents:

- Getting started
- Installation - Examples - Related packages - Recommended packages - Adding @ngx-cache/core to your project (SystemJS)
- app.module configuration
- Settings - Setting up CacheModule to use CacheStaticLoader
- SPA/Browser platform implementation
- Server platform implementation
- Usage
- Decorators
- Cached method decorator
- CacheKey parameter decorator
- Credits
- License

Getting started

$3

You can install @ngx-cache/core using npm

``
npm install @ngx-cache/core --save
`

$3

- [ng-seed/universal] is an officially maintained seed project, showcasing common patterns and best practices for @ngx-cache/core.

$3

The following packages may be used in conjunction with @ngx-cache/core:

- [@ngx-cache/platform-browser]
- [@ngx-cache/platform-server]
- [@ngx-cache/fs-storage]

$3

The following package(s) have no dependency for @ngx-cache/core, however may provide supplementary/shorthand functionality:

- [@ngx-config/core]: provides cache settings from the application settings loaded during application initialization

$3

Add map for @ngx-cache/core in your systemjs.config

`javascript
'@ngx-cache/core': 'node_modules/@ngx-cache/core/bundles/core.umd.min.js'
`

$3

Import CacheModule using the mapping '@ngx-cache/core' and append CacheModule.forRoot({...}) within the imports property
of app.module (_considering the app.module is the core module in Angular application_).

#### app.module.ts

`TypeScript
...
import { CacheModule } from '@ngx-cache/core';
...

@NgModule({
declarations: [
AppComponent,
...
],
...
imports: [
...
CacheModule.forRoot()
],
...
bootstrap: [AppComponent]
})
`

Settings

You can call the [forRoot] static method using CacheStaticLoader. By default, it is configured to have the cacheKey
as 'NGX_CACHE', and both expiry and TTL are set to Number.MAX_VALUE.

> You can customize this behavior (_and ofc other settings_) by supplying cache key and life span to CacheStaticLoader.

The following examples show the use of an exported function (_instead of an inline function_) for [AoT compilation].

$3

`TypeScript
...
import { CacheModule, CacheLoader, CacheStaticLoader } from '@ngx-cache/core';
...

export function cacheFactory(): CacheLoader {
return new CacheStaticLoader({
key: 'NGX_CACHE',
lifeSpan: {
"expiry": Number.MAX_VALUE,
"TTL": Number.MAX_VALUE
}
});
}

@NgModule({
declarations: [
AppComponent,
...
],
...
imports: [
CacheModule.forRoot({
provide: CacheLoader,
useFactory: (cacheFactory)
}),
...
],
...
bootstrap: [AppComponent]
})
`

CacheStaticLoader has one parameter:

- providedSettings: CacheSettings : cache settings
- key: string : cache key, used as object identifier while transferring between server and browser
platforms (_by default, 'NGX_CACHE'_)
- lifeSpan: LifeSpan : cache life span (_by default, both expiry and TTL are set to Number.MAX_VALUE_)

> :+1: Good! @ngx-cache/core is now ready to provide caching features.

Note: You need to perform browser ([@ngx-cache/platform-browser]), and (_for Angular Universal_) server ([@ngx-cache/platform-server])
platform implementations to begin using caching features.

SPA/Browser platform implementation

[@ngx-cache/platform-browser] provides the SPA/Browser platform implementation (_ex: MemoryCacheService, LocalStorageCacheService_).

You can find detailed information about the usage guidelines for the SPA/Browser platform here.

Server platform implementation

[@ngx-cache/platform-server] provides the server platform implementation (_ex: FsCacheService_).

You can find detailed information about the usage guidelines for the server platform here.

Usage

CacheService has the following properties:

- key: gets the KEY of CacheService, provided by CacheLoader, used as a key during state transferring

CacheService has the following methods:

- getInstance(loader?: CacheLoader, platformId?: any, injector?: Injector): gets the current instance of CacheService
- normalizeKey(key: string | number): normalizes the given key
- has(key: string | number): checks if an object is stored in CACHE, by key
- get(key: string | number): gets some object from CACHE, with ReturnType (_Scalar, Observable or Promise_)
and LifeSpan, by key
- getWithMetadata(key: string | number): gets some object from CACHE, by key
- set(key: string | number, value: any, returnType: ReturnType = ReturnType.Scalar, lifeSpan?: LifeSpan): puts some
object to CACHE
- remove(key: string | number, wild = false): removes some object from CACHE, by key
- clear(): removes all objects from CACHE
- dehydrate(): converts the data from CACHE to JSON (\*ex: transferring CACHE data from the server platform to
the client platform\*)
- 'rehydrate(json: any)': converts the given JSON value to CACHE data

The following example shows simple usage of the CacheService.

#### anyclass.ts

`TypeScript
...
import { CacheService } from '@ngx-cache/core';

@Injectable()
export class AnyClass {
constructor(private readonly cache: CacheService) {
// note that CacheService is injected into a private property of AnyClass
}

// will retrieve 'some string value'
getSomeStringValue(): string {
if (this.cache.has('some-string'))
return this.cache.get('some-string');

this.cache.set('some-string', 'some string value');
return 'some string value';
}
}
`

Decorators

> To enable experimental support for decorators, you must enable the experimentalDecorators compiler option in your
> tsconfig.json:

#### tsconfig.json

`JSON
{
"compilerOptions": {
"target": "ES5",
"experimentalDecorators": true
}
}
`

$3

Cached method decorator allows you to cache the an entire method (_with less amount of code, as well as without injecting
the CacheService_), by putting the return value to CACHE on the first execution, and retrieve it from CACHE on
the further executions.

Cached method has one parameter:

- key: string : obviously used as a key when putting/getting the method's value

$3

You can place CacheKey parameter decorator just before the parameter, and its value will be appended to the cache key.

The following example shows simple usage of the Cached and CacheKey decorators.

#### anyclass.ts

`TypeScript
...
import { Cached, CacheKey } from '@ngx-cache/core';

export class AnyClass {
// will retrieve 'some string value'
@Cached('some-string')
getSomeStringValue(): string {
return 'some string value';
}

@Cached('some-string')
getSomeStringValue2(@CacheKey param1: string): string {
return 'some string value: ' + param1;
}
}

...
// these are the first executions
console.log(anyClass.getSomeStringValue2('p1'));
console.log(anyClass.getSomeStringValue2('p2'));
...
// will retrieve 'some string value: p1' from CACHE
console.log(anyClass.getSomeStringValue2('p1'));

// will retrieve 'some string value: p1' from CACHE
console.log(anyClass.getSomeStringValue2('p2'));
``

Credits

- ng2-cache: Client side caching service for Angular2
- angular2-cache: An implementation of cache at Angular2
- universal-starter: Angular 2 Universal starter kit by @AngularClass

License

The MIT License (MIT)

Copyright (c) 2019 [Burak Tasci]

[ng-seed/universal]: https://github.com/ng-seed/universal
[@ngx-cache/platform-browser]: https://github.com/fulls1z3/ngx-cache/tree/master/packages/@ngx-cache/platform-browser
[@ngx-cache/platform-server]: https://github.com/fulls1z3/ngx-cache/tree/master/packages/@ngx-cache/platform-server
[@ngx-cache/fs-storage]: https://github.com/fulls1z3/ngx-cache/tree/master/packages/@ngx-cache/fs-storage
[@ngx-config/core]: https://github.com/fulls1z3/ngx-config/tree/master/packages/@ngx-config/core
[forroot]: https://angular.io/docs/ts/latest/guide/ngmodule.html#!#core-for-root
[aot compilation]: https://angular.io/docs/ts/latest/cookbook/aot-compiler.html
[burak tasci]: https://github.com/fulls1z3