ngx-liquid-cache

LiquidCache: a powerful, automatic and optimized Angular2/10+ cache system that fits everywhere!

Main features

1. Works everywhere, guaranteed. Its decorator system let you cache every existing (or new) method in your project without change a single comma.
2. Persistent or in-memory cache: choose the best solution in every case. Persistent cache could be also shared between tabs and windows.
3. Optimized under every aspect: observables will be cached before the result to be automatically shared between observers (with share operator from rxjs) and then converted to store the real result. Not-observable responses will be cached instantly;
4. An active cache expiration check system ensure that your methods return fresh data after a specific time frame, also for persistent data.
5. High configurability, from global settings to single-cache object.
6. Decorators and main service: you can use one or both of them to have max control over your cache system.
7. The library loads before the application thanks to Angular's APP_INITIALIZER injection token, ensuring that cache service is already operative at the application's startup.

Getting started

Install the library in your Angular project:

npm i --save ngx-liquid-cache

Fast Setup (zero configuration)

1 - Import NgxLiquidCacheModule in app.module.ts:

//...
import { NgxLiquidCacheModule } from 'ngx-liquid-cache';

@NgModule({
  //...
  imports: [
    //...
    NgxLiquidCacheModule.forRoot()
  ],
  //...
})
export class AppModule { }

2 - Use the @LiquidCache decorator in any method that return a result. Don't worry about the type of the returned value or about making adaptations to your code: LiquidCache is perfectly integrable with every existing method without change anything.

The key argument could be static (ex. 'myKey') or dynamic, using special placeholders ({placeholder name}) that will collect data from the original method's arguments (ex. mySingleKey{id}).

IMPORTANT: be sure to run the production build of your projects with optimization set to false in angular.json if using Angular 9 or prior, or placeholders won't work:

import { LiquidCache } from 'ngx-liquid-cache';

// Observable Example
export class ApiService {

  constructor(
      private http: HttpClient,
  ) { }

  @LiquidCache('users')
  getUsers() {
      console.log('getUsers Call');
      return this.http.get('users');
  }
  
  // Assuming to invoke getSingleUser(1), the result 
  // will be stored in the cache system with key 'user1'
  @LiquidCache('user{id}')
  getSingleUser(id) {
      return this.http.get('users/' + id);
  }
  
}

// Sync Example
export class UtilsService {

  @LiquidCache('calcResult')
  longCalc() {
      console.log('longCalc Call');
      let a  = 0;
      for (let i = 0; i < 100000000; i++) {
          a += i;
      }
      return a;
  }
}

3 - Call your methods and see the magic: original methods will be executed only the first time you invoke them. After the first call you will receive the cached result, speeding up your application.

// Automatic Example (cache by decorators)
export class ExampleComponent {

  constructor(
      private apiService: ApiService,
      private utilsService: UtilsService,
  ) { }

  testObservable() {
      this.apiService.getUsers.subscribe(result => console.log('First call', result));
      this.apiService.getUsers.subscribe(result => console.log('Second call', result));
      
      // Console output:
      // getUsers Call
      // First call (...)
      // Second call (...)
  }
  
  testSync() {
      console.log('First call', this.utilsService.longCalc());
      console.log('Second call', this.utilsService.longCalc());
      
      // Console output:
      // longCalc Call
      // First call (...)
      // Second call (...)
  }
}

4 - You can also use LiquidCacheService to interact directly with your cache:

import { LiquidCacheService } from 'ngx-liquid-cache';

// Manual Example
export class ExampleComponent {

  constructor(
      private cache: LiquidCacheService,
  ) { }

  testManual() {
      this.cache.set('testKey', 10);
      console.log('Data from cache', this.cache.get('testKey'));
      this.cache.remove('testKey'); // Remove element from cache
      
      // You can of course interact also with cache data generated by decorators
      console.log('Data from decorator', this.cache.get('users')); // 'users' is the key used in the apiService's decorator
  }
}

Configuration

The configuration for LiquidCache is divided in three parts: Global, Decorator and Object.

Here's the full configuration parameters list:

Parameter | Type | Default | Description --- | --- | --- | --- duration | number | null | The duration for cached elements (in seconds). A trigger will remove expired objects from the cache system. localStoragePrefix | string | ngxlc- | When saved to persistent cache, your keys will be prefixed with this value to avoid conflicts with other applications. This operation is invisible so you don't have to worry about change keys inside your application code. shareBetweenTabs | boolean | true | When this parameter is set to true, updates to your cache data will be detected from your application opened in other tabs/windows. This allow multiple instances of your application to be always synchronized. storageType | LiquidCacheStorageTypes | LiquidCacheStorageTypes.inMemory | Choose the storage type between LiquidCacheStorageTypes.inMemory and LiquidCacheStorageTypes.localStorage.

Global configuration

You can pass a LiquidCacheConfig object to the NgxLiquidCacheModule.forRoot() method to specify the global configuration for your cache system.

//...
import { NgxLiquidCacheModule, LiquidCacheConfig } from 'ngx-liquid-cache';

const liquidCacheConfig: LiquidCacheConfig = {
  //...
};

@NgModule({
  //...
  imports: [
    //...
    NgxLiquidCacheModule.forRoot(liquidCacheConfig)
  ],
  //...
})
export class AppModule { }

Decorator configuration

The @LiquidCache decorator accepts two arguments: key (string, required) and configuration (LiquidCacheConfig, optional). The configuration argument accepts a LiquidCacheConfig object, so you can pass a specific configuration for this single decorator:

export class ApiService {
  
  // Uses a specific configuration
  @LiquidCache('user{id}', { duration: 60 })
  getSingleUser(id) { ... }
  
  // Will use the global configuration
  @LiquidCache('users')
  getUsers() { ... }
}

Object configuration

You can set a specific configuration for every cache key that you will create:

import { LiquidCacheService, LiquidCacheConfig } from 'ngx-liquid-cache';

export class TestComponent {

  constructor(
      private cache: LiquidCacheService,
  ) { }

  test() {
      const specificConf: LiquidCacheConfig = { duration: 60 };
      this.cache.set('myKey', 'cached value', specificConf);
  }
}

Known issues

1. Angular 9 or prior: To use nominative placeholders with decorators (ex. user{id}) be sure to run the production build with optimizationset to false in your angular.json file.

Example

Clone the demo project from GitHub and run it with ng serve. Check the browser console to see the demo in action.

Coming soon

1. Specify group name for decorators that uses placeholders to simplify the removal of them.
2. Use custom callbacks and hooks during the cache lifecycle.

Suggestions, improvements, issues and more

Have you used this plugin in your project?

Say hello with a tweet!

Wanna improve this library?

The library source code lives inside the demo project on GitHub. Fork it and work! ;)

Need support?

Feel free to contact me at [email protected] or just open an issue on the official repository on GitHub.

License

MIT License - Copyright (c) Alberto Fecchi

Full license here