feat: Add Redis Key-Value Backend With TTL and Sorted Sets

README.md

@@ -4,7 +4,7 @@ One domain, many stores: the same activity feed modeled on relational, document,
 
 ## What this demonstrates
 
-Polyglot persistence is the idea that one product rarely has one ideal database. A follow graph wants adjacency lookups, a home timeline wants a clustered time key, and a unique handle wants a relational constraint. This repo keeps one domain and one `ActivityStore` port, then implements that port on each paradigm so query shape, consistency, and scaling stay comparable. The in-memory backend is fan-in on read: per-author timelines merged into a home feed. The Postgres backend is the same port over a 3NF schema, composite B-tree indexes, and keyset SQL. Later backends (Redis, MongoDB, Cassandra, CockroachDB, Neo4j) keep the same interface and the same contract tests.
+Polyglot persistence is the idea that one product rarely has one ideal database. A follow graph wants adjacency lookups, a home timeline wants a clustered time key, and a unique handle wants a relational constraint. This repo keeps one domain and one `ActivityStore` port, then implements that port on each paradigm so query shape, consistency, and scaling stay comparable. The in-memory backend is fan-in on read: per-author timelines merged into a home feed. The Postgres backend is the same port over a 3NF schema, composite B-tree indexes, and keyset SQL. The Redis backend speaks HASH, SET, ZSET, and SET NX, plus per-key PEXPIRE. Later backends (MongoDB, Cassandra, CockroachDB, Neo4j) keep the same interface and the same contract tests.
 
 ## Concepts demonstrated
 
@@ -22,17 +22,22 @@ Polyglot persistence is the idea that one product rarely has one ideal database.
 - Fan-in via `CROSS JOIN LATERAL`: each followee's newest-N posts walk `posts_author_timeline_idx`, then the outer query merges
 - Table-level `CHECK` (no self-follow) and `UNIQUE` (handle) as the source of integrity
 - Query planner: after `ANALYZE`, `EXPLAIN` on the author timeline is `Index Scan using posts_author_timeline_idx` with no Sort. The lateral feed uses that same scan per followee.
+- Redis key design: `u:{id}` HASH, `h:{handle}` STRING, `p:{id}` HASH, `tl:{author}` ZSET, `fg:{id}` / `fr:{id}` SET
+- SET NX as an application uniqueness primitive; sorted-set timeline (score = `createdAt`, member = post id, equal scores reverse-lex)
+- Per-key TTL (`PEXPIRE`) versus a relational `PRIMARY KEY`: the hash can vanish, the ZSET member lingers until the next read `ZREM`s it, and the id is reusable
+- No foreign keys and no `CHECK`: self-follow and existence are enforced in the store, not the engine
 
 ## What's implemented
 
 - Project scaffold with TypeScript strict mode, Vitest, and CI
 - Activity-feed domain, `ActivityStore` port, in-memory backend, and a shared contract suite
 - Relational backend (Postgres): schema, indexes, the SQL queries for the domain
+- Key-value backend (Redis): data structures + expiry, the tradeoffs vs relational
 
 ## Usage
 
 ```ts
-import { MemoryStore } from 'polyglot-persistence'
+import { MemoryRedis, MemoryStore, RedisStore } from 'polyglot-persistence'
 
 const store = new MemoryStore()
 
@@ -47,9 +52,18 @@ const post = await store.publish(
 
 const page = await store.feed('ada', { limit: 20 })
 const next = await store.feed('ada', { limit: 20, before: post })
+
+const redis = RedisStore.attach(new MemoryRedis())
+await redis.createUser({ id: 'ada', handle: 'ada' })
+await redis.publish({ id: 'p1', authorId: 'ada', body: 'ttl demo' }, Date.now())
+await redis.expirePost('p1', 60_000)
 ```
 
-`PostgresStore` takes any `{ query(sql, params) }` client. Tests drive it with PGlite (`@electric-sql/pglite` is a devDependency, not a runtime dep). A server `pg` Pool works the same way. A new backend implements `ActivityStore` and calls `defineStoreContract(name, factory)` from `test/contract.ts`.
+`PostgresStore` takes any `{ query(sql, params) }` client. Tests drive it with PGlite (`@electric-sql/pglite` is a devDependency, not a runtime dep). A server `pg` Pool works the same way.
+
+`RedisStore` takes any `RedisCommands` client (GET/SET NX, HASH, SET, ZSET, PEXPIRE). `MemoryRedis` is an in-process engine with the same types and per-key TTL, so the contract runs without a daemon. Point the same store at a real Redis by implementing that command surface.
+
+A new backend implements `ActivityStore` and calls `defineStoreContract(name, factory)` from `test/contract.ts`.
 
 ## Running the tests
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "polyglot-persistence",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One domain modeled across relational, document, key-value, wide-column, distributed SQL, and graph stores. A reference for when to reach for which database.",
   "type": "module",
   "license": "MIT",

src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = '0.2.0'
+export const VERSION = '0.3.0'
 export { BODY_MAX, StoreError } from './domain'
 export type {
   FeedCursor,
@@ -13,3 +13,5 @@ export type { ActivityStore, CreateUserInput, PublishInput } from './store'
 export { MemoryStore } from './memory-store'
 export { PostgresStore, SCHEMA_STATEMENTS, SQL } from './postgres/store'
 export type { SqlQuery } from './postgres/store'
+export { MemoryRedis, RedisStore } from './redis/store'
+export type { RedisCommands } from './redis/store'

src/redis/memory.ts

@@ -0,0 +1,176 @@
+export interface RedisCommands {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string, opts?: { nx?: boolean }): Promise<boolean>
+  del(...keys: string[]): Promise<number>
+  hset(key: string, fields: Record<string, string>): Promise<number>
+  hsetnx(key: string, field: string, value: string): Promise<boolean>
+  hgetall(key: string): Promise<Record<string, string>>
+  sadd(key: string, member: string): Promise<number>
+  srem(key: string, member: string): Promise<number>
+  sismember(key: string, member: string): Promise<boolean>
+  smembers(key: string): Promise<string[]>
+  zadd(key: string, score: number, member: string): Promise<number>
+  zrem(key: string, member: string): Promise<number>
+  zcard(key: string): Promise<number>
+  zrevrangebyscore(
+    key: string,
+    max: number,
+    min: number,
+  ): Promise<Array<{ member: string; score: number }>>
+  pexpire(key: string, ttlMs: number): Promise<boolean>
+  pttl(key: string): Promise<number>
+}
+
+type Rec =
+  | { t: 'string'; v: string; exp?: number }
+  | { t: 'hash'; v: Map<string, string>; exp?: number }
+  | { t: 'set'; v: Set<string>; exp?: number }
+  | { t: 'zset'; v: Map<string, number>; exp?: number }
+
+export class MemoryRedis implements RedisCommands {
+  private readonly keys = new Map<string, Rec>()
+
+  constructor(private readonly clock: () => number = Date.now) {}
+
+  async get(key: string): Promise<string | null> {
+    const rec = this.as(key, 'string')
+    return rec ? rec.v : null
+  }
+
+  async set(key: string, value: string, opts?: { nx?: boolean }): Promise<boolean> {
+    const live = this.alive(key)
+    if (opts?.nx && live) return false
+    if (live && live.t !== 'string') throw new Error('WRONGTYPE')
+    this.keys.set(key, { t: 'string', v: value })
+    return true
+  }
+
+  async del(...keys: string[]): Promise<number> {
+    let n = 0
+    for (const key of keys) {
+      if (this.alive(key)) n++
+      this.keys.delete(key)
+    }
+    return n
+  }
+
+  async hset(key: string, fields: Record<string, string>): Promise<number> {
+    const rec = this.ensure(key, 'hash', () => ({ t: 'hash', v: new Map() }))
+    let added = 0
+    for (const [field, value] of Object.entries(fields)) {
+      if (!rec.v.has(field)) added++
+      rec.v.set(field, value)
+    }
+    return added
+  }
+
+  async hsetnx(key: string, field: string, value: string): Promise<boolean> {
+    const rec = this.ensure(key, 'hash', () => ({ t: 'hash', v: new Map() }))
+    if (rec.v.has(field)) return false
+    rec.v.set(field, value)
+    return true
+  }
+
+  async hgetall(key: string): Promise<Record<string, string>> {
+    const rec = this.as(key, 'hash')
+    if (!rec) return {}
+    return Object.fromEntries(rec.v)
+  }
+
+  async sadd(key: string, member: string): Promise<number> {
+    const rec = this.ensure(key, 'set', () => ({ t: 'set', v: new Set() }))
+    const before = rec.v.size
+    rec.v.add(member)
+    return rec.v.size - before
+  }
+
+  async srem(key: string, member: string): Promise<number> {
+    const rec = this.as(key, 'set')
+    if (!rec) return 0
+    return rec.v.delete(member) ? 1 : 0
+  }
+
+  async sismember(key: string, member: string): Promise<boolean> {
+    const rec = this.as(key, 'set')
+    return rec ? rec.v.has(member) : false
+  }
+
+  async smembers(key: string): Promise<string[]> {
+    const rec = this.as(key, 'set')
+    return rec ? [...rec.v] : []
+  }
+
+  async zadd(key: string, score: number, member: string): Promise<number> {
+    const rec = this.ensure(key, 'zset', () => ({ t: 'zset', v: new Map() }))
+    const added = rec.v.has(member) ? 0 : 1
+    rec.v.set(member, score)
+    return added
+  }
+
+  async zrem(key: string, member: string): Promise<number> {
+    const rec = this.as(key, 'zset')
+    if (!rec) return 0
+    return rec.v.delete(member) ? 1 : 0
+  }
+
+  async zcard(key: string): Promise<number> {
+    const rec = this.as(key, 'zset')
+    return rec ? rec.v.size : 0
+  }
+
+  async zrevrangebyscore(
+    key: string,
+    max: number,
+    min: number,
+  ): Promise<Array<{ member: string; score: number }>> {
+    const rec = this.as(key, 'zset')
+    if (!rec) return []
+    return [...rec.v.entries()]
+      .filter(([, score]) => score <= max && score >= min)
+      .sort((a, b) => (a[1] === b[1] ? (a[0] < b[0] ? 1 : -1) : b[1] - a[1]))
+      .map(([member, score]) => ({ member, score }))
+  }
+
+  async pexpire(key: string, ttlMs: number): Promise<boolean> {
+    const rec = this.alive(key)
+    if (!rec || ttlMs < 1) return false
+    rec.exp = this.clock() + ttlMs
+    return true
+  }
+
+  async pttl(key: string): Promise<number> {
+    const rec = this.alive(key)
+    if (!rec) return -2
+    if (rec.exp === undefined) return -1
+    return Math.max(0, rec.exp - this.clock())
+  }
+
+  private alive(key: string): Rec | undefined {
+    const rec = this.keys.get(key)
+    if (!rec) return undefined
+    if (rec.exp !== undefined && rec.exp <= this.clock()) {
+      this.keys.delete(key)
+      return undefined
+    }
+    return rec
+  }
+
+  private as<T extends Rec['t']>(key: string, t: T): Extract<Rec, { t: T }> | undefined {
+    const rec = this.alive(key)
+    if (!rec) return undefined
+    if (rec.t !== t) throw new Error('WRONGTYPE')
+    return rec as Extract<Rec, { t: T }>
+  }
+
+  private ensure<T extends Rec['t']>(
+    key: string,
+    t: T,
+    make: () => Extract<Rec, { t: T }>,
+  ): Extract<Rec, { t: T }> {
+    const rec = this.as(key, t)
+    if (rec) return rec
+    const created = make()
+    this.keys.set(key, created)
+    return created
+  }
+}