@cutticat/storages

Key-value storage library with TTL support.

Contents

• Overview
• Installation
• Quick start
• Entry points
• API
• Documentation
• Requirements

Overview

The library provides a Storage<T> interface (set, get, delete, clear) and implementations:

• NullStorage — empty storage (for tests and mocks)
• InMemoryStorage — stores values in memory (any type, no serialization)
• FileStorage — stores JSON files on disk (Node.js)
• RedisStorage — stores JSON in Redis with optional Zod validation
• PgStorage — stores JSON in PostgreSQL with optional Zod validation

All storages support optional time-to-live (TTL) for entries.

Installation

pnpm i @cutticat/storages

Node.js storages require peer dependencies:

pnpm i redis   # for RedisStorage
pnpm i pg      # for PgStorage

FileStorage uses @cutticat/fs-extras (included as a dependency).

Quick start

import { InMemoryStorage } from "@cutticat/storages"

const storage = new InMemoryStorage<string>()
await storage.set("key", "value", 60000)
const value = await storage.get("key")

With Redis and a Zod schema:

import { z } from "zod"
import { createClient } from "redis"
import { RedisStorage } from "@cutticat/storages/node"

const client = createClient({ url: "redis://localhost:6379" })
await client.connect()

const schema = z.object({ id: z.number(), name: z.string() })
const storage = new RedisStorage({
  client,
  prefix: "app:",
  schema,
})

await storage.set("user:1", { id: 1, name: "John" }, 60000)
const user = await storage.get("user:1")

Entry points

• @cutticat/storages — neutral: Storage, InMemoryStorage, NullStorage.
• @cutticat/storages/node — node: same + FileStorage, RedisStorage, PgStorage (require redis / pg).

API

Storage<T> (interface)

• set(key, value, ttl?) — stores a value with optional TTL (ms)
• get(key) — returns the value or undefined
• delete(key) — removes an entry
• clear() — clears the storage

NullStorage<T>

Empty storage: stores nothing, always returns undefined. For tests and mocks.

InMemoryStorage<T>

In-memory storage. Stores values as-is (no JSON). Suitable for any type.

FileStorage<T>

File system storage (Node.js). Stores each value in a separate JSON file. Uses @cutticat/fs-extras.

Options:

• rootDir — root directory for files
• schema — optional Zod schema for validation on read
• throwOnParseError — when true, throws on invalid data (default false)
• throwOnReadError — when true, throws on file read errors (default false)
• now — function to get the current time (default Date.now, useful for tests)
• keyToPath — function to map a key to a file path (default base64url, useful for tests)

RedisStorage<T>

Redis storage. Serializes to JSON on write, deserializes on read.

Options:

• client — Redis client
• prefix — prefix for all keys
• schema — optional Zod schema for validation on read
• throwOnParseError — when true, throws on invalid data (default false, returns undefined)

PgStorage<T>

PostgreSQL storage. Serializes to JSON on write, deserializes on read. Creates the table on first access.

Options:

• pool — pg connection pool
• tableName — table name (default cutticat_pg_storage)
• schema — optional Zod schema for validation on read
• throwOnParseError — when true, throws on invalid data (default false, returns undefined)
• now — function to get the current time (default Date.now, useful for tests)

Documentation

See also:

• Project structure
• Scripts
• Style guide
• Contributing

Full API documentation is available in JSDoc comments.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0
• redis >= 4.7.0 (for RedisStorage)
• pg >= 8.0.0 (for PgStorage)