Provider-neutral ephemeral caching for Pegma hosts:
typed key namespaces, cache-aside getOrCompute with stampede protection,
and a conformance suite every adapter must pass.
Important
Pegma is in early 0.x development. Packages are not published yet. No
public API is stable.
- Strict key namespacing with schema-aware codecs (JSON and binary)
- Cache-aside
getOrComputewith single-flight coalescing and optional probabilistic early expiration (XFetch) - Sliding and absolute TTL via an injected Spine
Clock - Fail-open / fail-closed fallback policies
- A conformance suite every adapter must pass
- Durability guarantees — durable state belongs in
@pegma/storage-core - Implicit cross-partition multi-key ops; Redis Cluster hash tags are in the contract
- Unbounded local memory fallbacks when a remote cache is down
- Vendor clients leaking into application code
| Package | Role | Phase |
|---|---|---|
@pegma/cache-core |
Port, codecs, single-flight, memory store | 1 |
@pegma/cache-conformance |
Executable suite every adapter must pass | 1 |
@pegma/cache-redis |
Generic Redis adapter | 2 |
@pegma/cache-azure-redis |
Azure Cache for Redis adapter | 3 |
@pegma/cache-elasticache |
Amazon ElastiCache adapter | 4 |
@pegma/cache-upstash-redis |
Upstash Redis adapter | 5 |
@pegma/cache-redis is the generic Redis adapter.
@pegma/cache-azure-redis and @pegma/cache-elasticache are thin
compositions of it: Azure Cache for Redis and ElastiCache speak Redis.
@pegma/cache-upstash-redis wraps the Upstash serverless REST client
and reuses that store after adapting the HTTP command surface. Intended
future hosts: RetireGolden.org and Exsimplify. Do not create further
adapter packages here.
The conformance suite is the specification. A behaviour not asserted there is not something a host may rely on. An adapter is finished when it passes the suite.
- Project plan — phases, scope, and decisions
- Releasing — trusted-publisher release runbook
Requires Node.js 22 or 24. Corepack is bundled through Node 24; on Node 25 or newer, install it first.
npm install -g corepack
corepack enable
pnpm install --frozen-lockfile
pnpm run format:check
pnpm run check
pnpm test
pnpm run test:redis
pnpm run test:azure-redis
pnpm run test:elasticache
pnpm run test:upstash-redispnpm test is the Phase 1 gate and does not need Redis. pnpm run test:redis,
pnpm run test:azure-redis, pnpm run test:elasticache, and
pnpm run test:upstash-redis start a local redis-server on port 16379
when that port is free, or use whatever is already listening there. The
Upstash suite injects a REST-shaped client; @upstash/redis cannot speak
the Redis protocol to that service.
MIT © 2026 RetireGolden, LLC
