# extra-disk-cache

> A disk-based persistent cache.

Latest version **0.13.0** (published 2026-03-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install extra-disk-cache
pnpm add extra-disk-cache
yarn add extra-disk-cache
bun add extra-disk-cache
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.13.0 |
| Published | 2026-03-01 |
| First published | 2021-09-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 14 |
| Unpacked size | 71.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | BlackGlory |
| Maintainers | black_glory |

## Links

- npm: https://www.npmjs.com/package/extra-disk-cache
- Repository: https://github.com/BlackGlory/extra-disk-cache
- Homepage: https://github.com/BlackGlory/extra-disk-cache#readme
- Issues: https://github.com/BlackGlory/extra-disk-cache/issues
- npm.io page: https://npm.io/package/extra-disk-cache

## Dependencies (14)

- [extra-lazy](https://npm.io/package/extra-lazy.md) ^2.0.2
- [extra-utils](https://npm.io/package/extra-utils.md) ^6.0.0
- [extra-timers](https://npm.io/package/extra-timers.md) ^0.3.0
- [msgpack-lite](https://npm.io/package/msgpack-lite.md) ^0.1.26
- [return-style](https://npm.io/package/return-style.md) ^4.0.0
- [extra-promise](https://npm.io/package/extra-promise.md) ^7.1.1
- [better-sqlite3](https://npm.io/package/better-sqlite3.md) ^12.6.2
- [lz4-wasm-nodejs](https://npm.io/package/lz4-wasm-nodejs.md) ^0.9.2
- [migration-files](https://npm.io/package/migration-files.md) ^0.4.3
- [@mongodb-js/zstd](https://npm.io/package/@mongodb-js/zstd.md) ^1.2.0
- [extra-filesystem](https://npm.io/package/extra-filesystem.md) ^0.6.2
- [iterable-operator](https://npm.io/package/iterable-operator.md) ^6.0.0
- [@blackglory/prelude](https://npm.io/package/@blackglory/prelude.md) ^0.4.0
- [@blackglory/better-sqlite3-migrations](https://npm.io/package/@blackglory/better-sqlite3-migrations.md) ^0.2.2

## Recent versions

- 0.13.0 (latest) — 2026-03-01
- 0.12.6 — 2026-02-17
- 0.12.5 — 2026-02-17
- 0.12.4 — 2025-11-03
- 0.12.3 — 2025-07-21
- 0.12.2 — 2025-05-25
- 0.12.1 — 2024-09-24
- 0.12.0 — 2024-02-15
- 0.11.2 — 2023-06-10
- 0.11.1 — 2022-12-21
- 0.11.0 — 2022-12-21
- 0.10.1 — 2022-12-12
- 0.10.0 — 2022-12-11
- 0.9.0 — 2022-12-10
- 0.8.23 — 2022-12-05
- … 41 more at https://npm.io/package/extra-disk-cache/versions

## README

# extra-disk-cache
A disk-based persistent cache.

## Install
```sh
npm install --save extra-disk-cache
# or
yarn add extra-disk-cache
```

## Usage
```ts
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
```ts
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>
}
```

### DiskCacheWithCache
```ts
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>
}
```

### DiskCacheView
```ts
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
```ts
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>
}
```

### Converters
#### PassthroughKeyConverter
```ts
class PassthroughKeyConverter implements IKeyConverter<string>, IKeyAsyncConverter<string>
```

#### PassthroughValueConverter
```ts
class PassthroughValueConverter implements IValueConverter<Buffer>, IValueAsyncConverter<Buffer>
```

#### JSONKeyConverter
```ts
class JSONKeyConverter<T> implements IKeyConverter<T>, IKeyAsyncConverter<T>
```

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

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

#### MessagePackValueConverter
```ts
class MessagePackValueConverter<T> implements IValueConverter<T>, IValueAsyncConverter<T>
```

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

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

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

#### ZstandardValueAsyncConverter
```ts
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
```ts
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
```ts
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>
}
```

---
_Source: https://npm.io/package/extra-disk-cache · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._