@unikvs/lru-cache

How to use LruCache in @unikvs/lru-cache, an LRU storage that keeps arbitrary values with limits.

Overview

@unikvs/lru-cache is an LRU storage that keeps arbitrary values in memory with limits. It evicts least-recently-used entries first, so it works well as a cache.

name is LruCache.
Requires open and close. close discards all stored values.
Set limits with maxEntries and maxBytes. Both are optional.
Use size for the entry count and bytes for the byte count (when maxBytes is set).

Install with:

npm install @unikvs/lru-cache

pnpm add @unikvs/lru-cache

yarn add @unikvs/lru-cache

bun add @unikvs/lru-cache

nub add @unikvs/lru-cache

aube add @unikvs/lru-cache

Usage

LruCache implements IStorage. Pass it to UniKvs with persist().

import { LruCache } from "@unikvs/lru-cache";

Constructor arguments:

PropType

clone?(<T>(value: T) => T) | undefined

Function used to clone data. Uses structuredClone when omitted.

Type(<T>(value: T) => T) | undefined

DefaultstructuredClone

maxEntries?number | undefined

Maximum number of entries. Specify a non-negative integer.

Typenumber | undefined

maxBytes?number | undefined

Maximum total bytes. Specify a non-negative finite number.

Typenumber | undefined

sizeOf?((value: any, key: string) => number) | undefined

Function deciding per-key bytes. Defaults to byteLength for Uint8Array and 1 otherwise.

Type((value: any, key: string) => number) | undefined

The following example stores values with an entry-count limit.

import { LruCache } from "@unikvs/lru-cache";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  greeting: unikvs.PlainValue<string>;
}>()
  .persist(new LruCache({ maxEntries: 100 }))
  .build();

await kvs.open();
await kvs.set("greeting", "hello");

const value = await kvs.get("greeting");
console.log(value); // "hello"

await kvs.close();

Data types

Operation	Supported data type
`write`/`read`	Arbitrary values (strings, objects, etc.)
`getWritable`/`getReadable` chunks	`Uint8Array<ArrayBuffer>`

Stores arbitrary values. Handles values cloneable with structuredClone, such as strings and objects.
Clones read/write values with structuredClone by default. Change it with the constructor clone option.
When maxEntries is exceeded, least-recently-used keys are evicted first. With maxEntries: 0, nothing is stored.
When maxBytes is set, older keys are evicted so total bytes stay within the limit.
Stream chunks support only Uint8Array<ArrayBuffer>.
Streams from getWritable concatenate written chunks and save them on close.
Streams from getReadable emit the stored value as a single chunk. Throws InvalidChunkTypeError when the stored value is not a Uint8Array.

Errors

This package throws the following errors.

KeyNotFoundError

Meaning

Thrown when the specified key does not exist. A shared error from @unikvs/core.

How to fix

Check with exists before reading.

Example

The following example catches KeyNotFoundError.

import { KeyNotFoundError } from "@unikvs/lru-cache";

try {
  await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("Key not found");
  } else {
    throw ex;
  }
}