extra-disk-cache

A disk-based persistent cache.

Install

npm install --save extra-disk-cache
# or
yarn add extra-disk-cache

Usage

import { DiskCache } from 'extra-disk-cache'
import ms from 'ms'

const cache = await DiskCache.create('/tmp/cache')
cache.set('key', Buffer.from('value'), ms('1h'))
const value = cache.get('key')?.toString()

API

DiskCache

class DiskCache {
  static create(filename?: string): Promise<DiskCache>

  close(): void
  has(key: string): boolean
  get(key: string): Buffer | undefined
  getWithMetadata(key: string): {
    value: Buffer
    updatedAt: number
    timeToLive: number | null
  } | undefined
  set(
    key: string
  , value: Buffer
    /**
     * `timeToLive > 0`: items will expire after `timeToLive` milliseconds.
     * `timeToLive = 0`: items will expire immediately.
     * `timeToLive = null`: items will not expire.
     */
  , timeToLive: number | null = null
  ): void
  delete(key: string): void
  clear(): void
  keys(): IterableIterator<string>
}

DiskCacheView

interface IKeyConverter<T> {
  toString: (value: T) => string
  fromString: (value: string) => T | undefined
}

interface IValueConverter<T> {
  toBuffer: (value: T) => Buffer
  fromBuffer: (value: Buffer) => T
}

class DiskCacheView<K, V> {
  constructor(
    cache: DiskCache | DiskCacheWithCache
  , keyConverter: IKeyConverter<K>
  , valueConverter: IValueConverter<V>
  )

  has(key: K): boolean
  get(key: K): V | undefined
  getWithMetadata(key: K): {
    value: V
    updatedAt: number
    timeToLive: number | null
  } | undefined
  set(
    key: K
  , value: V
    /**
     * `timeToLive > 0`: items will expire after `timeToLive` milliseconds.
     * `timeToLive = 0`: items will expire immediately.
     * `timeToLive = null`: items will not expire.
     */
  , timeToLive: number | null = null
  ): void
  delete(key: K): void
  clear(): void
  keys(): IterableIterator<K>
}

DiskCacheAsyncView

interface IKeyAsyncConverter<T> {
  toString: (value: T) => Awaitable<string>
  fromString: (value: string) => Awaitable<T | undefined>
}

interface IValueAsyncConverter<T> {
  toBuffer: (value: T) => Awaitable<Buffer>
  fromBuffer: (value: Buffer) => Awaitable<T>
}

class DiskCacheAsyncView<K, V> {
  constructor(
    cache: DiskCache | DiskCacheWithCache
  , keyConverter: IKeyAsyncConverter<K>
  , valueConverter: IValueAsyncConverter<V>
  )

  has(key: K): Promise<boolean>
  get(key: K): Promise<V | undefined>

  getWithMetadata(key: K): Promise<{
    value: V
    updatedAt: number
    timeToLive: number | null
  } | undefined>
  set(
    key: K
  , value: V
    /**
     * `timeToLive > 0`: items will expire after `timeToLive` milliseconds.
     * `timeToLive = 0`: items will expire immediately.
     * `timeToLive = null`: items will not expire.
     */
  , timeToLive: number | null = null
  ): Promise<void>
  delete(key: K): Promise<void>
  clear(): void
  keys(): AsyncIterableIterator<K>
}

DiskCacheWithCache

interface ICache {
  set(
    key: string
  , value:
    | {
        value: Buffer
        updatedAt: number
        timeToLive: number | null
      }
    | false
  , timeToLive?: number
  ): void

  get(key: string):
  | {
      value: Buffer
      updatedAt: number
      timeToLive: number | null
    }
  | false
  | undefined

  delete(key: string): void
  clear(): void
}

class DiskCacheWithCache {
  constructor(diskCache: DiskCache, memoryCache: ICache)

  close(): void
  has(key: string): boolean
  get(key: string): Buffer | undefined
  getWithMetadata(key: string): {
    value: Buffer
    updatedAt: number
    timeToLive: number | null
  } | undefined
  set(key: string, value: Buffer, timeToLive: number | null = null): void
  delete(key: string): void
  clear(): void
  keys(): IterableIterator<string>
}

Converters

PassthroughKeyConverter

class PassthroughKeyConverter implements IKeyConverter<string>, IKeyAsyncConverter<string>

PassthroughValueConverter

class PassthroughValueConverter implements IValueConverter<Buffer>, IValueAsyncConverter<Buffer>

JSONKeyConverter

class JSONKeyConverter<T> implements IKeyConverter<T>, IKeyAsyncConverter<T>

JSONValueConverter

class JSONValueConverter<T> implements IValueConverter<T>, IValueAsyncConverter<T> {
  constructor(encoding: BufferEncoding = 'utf-8')
}

IndexKeyConverter

class IndexKeyConverter implements IKeyConverter<number>, IKeyAsyncConverter<number> {
  constructor(radix: number = 10)
}

MessagePackValueConverter

class MessagePackValueConverter<T> implements IValueConverter<T>, IValueAsyncConverter<T>

LZ4ValueConverter

class LZ4ValueConverter<T> implements IValueConverter<T>, IValueAsyncConverter<T> {
  constructor(valueConverter: IValueConverter<T>)
}

LZ4ValueAsyncConverter

class LZ4ValueAsyncConverter<T> implements IValueAsyncConverter<T> {
  constructor(valueConverter: IValueConverter<T> | IValueAsyncConverter<T>)

  toBuffer(value: T): Promise<Buffer>
  fromBuffer(value: Buffer): Promise<T>
}

ZstandardValueAsyncConverter

class ZstandardValueAsyncConverter<T> implements IValueAsyncConverter<T> {
  constructor(
    valueConverter: IValueConverter<T> | IValueAsyncConverter<T>
  , level: number
  )

  toBuffer(value: T): Promise<Buffer>
  fromBuffer(value: Buffer): Promise<T>
}

PrefixKeyConverter

export class PrefixKeyConverter<T> implements IKeyConverter<T>, IKeyAsyncConverter<T> {
  constructor(
    keyConverter: IKeyConverter<T>
  , prefix: string
  )

  toString(value: T): string
  fromString(value: string): T | undefined
}

PrefixKeyAsyncConverter

class PrefixKeyAsyncConverter<T> implements IKeyAsyncConverter<T> {
  constructor(
    keyConverter: IKeyConverter<T> | IKeyAsyncConverter<T>
  , prefix: string
  )

  toString(value: T): Promise<string>
  fromString(value: string): Promise<T | undefined>
}