Common

Base module consisted of the architectural blocks for typical tramvai app. This module is required at most cases and is used a lot by the other modules.

Installation

First install @tramvai/module-common

npm i @tramvai/module-common

Add CommonModule to the modules list

import { createApp } from '@tramvai/core';
import { CommonModule } from '@tramvai/module-common';

createApp({
  modules: [CommonModule],
});

Explanation

Submodules

CommandModule

Module that adds implementation for the commandLineRunner and defines default command lines

This module logs with id command:command-line-runner

StateModule

Adds state-manager

ActionModule

Implements action system

This module logs with id action:action-page-runner

CookieModule

Add providers that works with cookie. See docs

EnvironmentModule

Implements work with environment variables both on server and client. See docs

PubSub

Provides PubSub interface to implement communication between components. See docs

This modules logs with id pubsub

LogModule

Module for logging. Uses @tramvai/module-log

CacheModule

Module that implements caches.

It provides next functionality:

• create new cache instance (instance of lru-cache by default)
• clear all of the previously create caches
• subscribe on cache clearance event to execute own cache clearance actions
• adds papi-route /clear-cache that will trigger caches clear event

This modules logs with id cache:papi-clear-cache

Cache types

You can create different cache types with CREATE_CACHE_TOKEN factory:

• LRU - @tinkoff/lru-cache-nano

  This type of cache is created by default. To create it explicitly you must pass 'memory' as the first argument, and options as the second.

  provide({
    provide: CACHE_TOKEN,
    scope: Scope.SINGLETON,
    useFactory: ({ createCache }) =>
      createCache('memory', {
        max: 100,
        ttl: 24 * 60 * 60 * 1000, // 1 day
        ttlResolution: 60 * 1000, // 1 minute
        allowStale: true,
        updateAgeOnGet: true,
      }),
    deps: {
      createCache: CREATE_CACHE_TOKEN,
    },
  });

• LFU - @akashbabu/lfu-cache

  To create it you must pass 'memory-lfu' as the first argument, cache options - as second.

  provide({
    provide: CACHE_TOKEN,
    scope: Scope.SINGLETON,
    useFactory: ({ createCache }) =>
      createCache('memory-lfu', {
        max: 20,
        evictCount: 5,
        maxAge: 24 * 60 * 60 * 1000, // 1 day
      }),
    deps: {
      createCache: CREATE_CACHE_TOKEN,
    },
  });

Cache metrics

To turn cache hit/miss rate monitoring, cache size, you need to provide cache name in options:

provide({
  provide: CACHE_TOKEN,
  scope: Scope.SINGLETON,
  useFactory: ({ createCache }) =>
    createCache('memory', {
      name: 'cache-name',
    }),
  deps: {
    createCache: CREATE_CACHE_TOKEN,
  },
});

Cache name have to be unique, factory will throw exception in case of cache name duplication.

Metric module should be provided in your application.

Server cache metrics:

• cache_hit{name, method} counter
• cache_miss{name, method} counter
• cache_max{name} gauge
• cache_size{name} gauge

By default hit/miss rate is computed as a sum of all data access attempts (methods has, peek, get).

RequestManagerModule

Wrapper for the client request

ResponseManagerModule

Wrapper for the client response

How to

Create cache

import { provide } from '@tramvai/core';

export const providers = [
  provide({
    provide: MY_MODULE_PROVIDER_FACTORY,
    scope: Scope.SINGLETON,
    useFactory: ({ createCache }) => {
      const cache = createCache('memory', ...args); // type of the cache and any additional options that will be passed to the cache constructor

      return someFactory({ cache });
    },
    deps: {
      createCache: CREATE_CACHE_TOKEN,
    },
  }),

  provide({
    provide: REGISTER_CLEAR_CACHE_TOKEN,
    scope: Scope.SINGLETON,
    useFactory: ({ cache }) => {
      return async () => {
        await cache.reset();
        console.log('my module cache cleared');
      };
    },
    deps: {
      cache: MY_MODULE_CACHE,
    },
  }),

  provide({
    provide: commandLineListTokens.clear,
    useFactory: ({ clearCache }) => {
      return function clear() {
        clearCache(); // clear caches explicitly
      };
    },
    deps: {
      clearCache: CLEAR_CACHE_TOKEN,
    },
  }),
];

Exported tokens

• tokens-common
• cookie
• env