README.md

cache-interop

Interoperable cache adapters for node and browsers.

About | Documentation

Warning Before v1 is released expect breaking changes in API

Features

• Simple but powerful API.
• Native promises /async/await.
• Don't throw errors.
• Typescript friendly.
• High quality & covergae, see e2e tests.
• Multiple adapters: node-redis, ioredis.

Roadmap

• Finalize v1 API
  • injectable LoggerInterface
  • SerializerInterface (json, msgpack, gzip, marshaller, superjson)
    • Chainable serializer (json -> gzip...)
  • Cache manager
    • Chainable cache adapter (allows lru as L1, redis as L2)
• Adapters
  • lru-cache
• Documentation

Contracts

package	targets	description	Info
@soluble/cache-interop	node,browser	Interoperability interfaces & contracts

Adapters

package	targets	description	Info
@soluble/cache-ioredis	node	Adapter for ioredis driver
@soluble/cache-redis	node	Adapter for node-redis driver

Utils

package	targets	description	Info
@soluble/dsn-parser	node,browser	Tiny and relaxed DSN parser

At a glance

import { IoRedisCacheAdapter } from "@soluble/cache-ioredis";

const cache = new IoRedisCacheAdapter({
  connection: "redis://localhost:6375",
});

const getSomething = async () => JSON.stringify({ success: true });

const { data, error } = await cache.getOrSet(
  // Cache key
  "cacke-key-v-1",
  // Async function
  getSomething,
  // GetOrSetOptions
  { ttl: 3600 }
);

if (error instanceof Error) {
  throw error;
}

let parsed;
try {
  parsed = JSON.parse(data);
} catch (e) {
  throw new SerializerException(e.message);
}

Diagram

classDiagram
    CacheInterface <|-- AbstractCacheAdapter
    CacheInterface: +getOrSet(key, valueOrFn, options) CacheItemInterface
    CacheInterface: +get(key, options) CacheItemInterface
    CacheInterface: +set(key, valueOrFn, options) boolean|CacheException
    CacheInterface: +has(key, options) boolean|undefined
    CacheInterface: +delete(key, options) boolean|CacheException
    CacheInterface: +getMultiple(keys, options) Map
    CacheInterface: +setMultiple(keyVals, options) Map
    CacheInterface: +deleteMultiple(keys, options) Map
    CacheInterface: +clear() true|CacheException
    class AbstractCacheAdapter {
      +string adapterName
      +getOrSet() CacheItemInterface
      +getMultiple(keyVals, options) Map
      +setMultiple(keyVals, options) Map
      +deleteMultiple(keys, options) Map
    }
    ConnectedCacheInterface <|-- RedisCacheAdapter
    ConnectedCacheInterface <|-- IoRedisCacheAdapter
    class ConnectedCacheInterface {
      +getConnection() ConnectionInterface
    }
    AbstractCacheAdapter <|-- IoRedisCacheAdapter
    class IoRedisCacheAdapter {
        +IoRedisConnection conn
        +string adapterName
    }
    AbstractCacheAdapter <|-- MapCacheAdapter
    class MapCacheAdapter {
        +string adapterName
    }
    AbstractCacheAdapter <|-- RedisCacheAdapter
    class RedisCacheAdapter {
        +RedisConnection conn
        +string adapterName
    }
    class ConnectionInterface {
        +getNativeConnection()
        +quit()
    }
    ConnectionInterface <|-- IoRedisConnection
    class IoRedisConnection {
       +quit()
    }
    ConnectionInterface <|-- RedisConnection
    class RedisConnection {
       +quit()
    }

Loading

Options

GetOrSetOptions	target	default	description
ttl	number	0	Time-To-Live in seconds since Epoch time. If zero, no expiry.
disableCache	boolean/{read: boolean, write: boolean}	false	Disable cache

Structure

This monorepo holds the various adapters, the contracts for interoperability and the e2e tests.

./packages
 ├── dsn-parser
 │   └── # @soluble/dsn-parser: utility for parsing connection dsn #
 ├── cache-interop
 │   └── # @soluble/cache-interop: cache interoperability contracts #
 ├── cache-ioredis
 │   └── # @soluble/cache-ioredis: ioredis adapter implementation #
 ├── cache-redis
 │   └── # @soluble/cache-redis: node redis adapter implementation #
 └── cache-e2e-tests
     └── # e2e test suite for all adapters #

Inspiration

• PSR-6 - PHP Cache interface standard recommendation.
• PSR-16 - PHP SimpleCache interface standard recommendation.
• Symfony cache - Symfony cache component.
• Node-cache-manager - Flexible NodeJS cache module.
• C# getOrSet - C# Memory::getOrSet() method.
• SWR - React Hooks library for data fetching

Acknowledgements

• microbundle - Zero-configuration bundler for tiny modules.
• node-testcontainers - Ephemeral docker instances to facilitate e2e on various services (redis...)
• atlassian/changesets - To ease pain with monorepo versioning.

Special thanks to

JetBrains	Embie.be