adobe / adobe/helix-shared

Create helix-shared-edge-kv for unified key-value store APIs

Open
#1,165 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
15
Forks
16
Avg merge
23h 18m
Merged PRs (30d)
14

Description

## Background

PR adobe/helix-deploy-plugin-edge#77 documents the API differences between Fastly Compute and Cloudflare Workers. Comment https://github.com/adobe/helix-deploy-plugin-edge/pull/77#issuecomment-3554569809 identifies the need for unified key-value store APIs across both platforms.

## Problem

Fastly and Cloudflare provide similar but incompatible KV APIs:

**Fastly KVStore:**
- Constructor: `new KVStore(name)`
- Returns entry objects: `entry.text()`, `entry.json()`, `entry.arrayBuffer()`
- No list operation
- No metadata support

**Cloudflare Workers KV:**
- Binding-based: `env.NAMESPACE`
- Returns values directly: `get(key, type)`
- Supports list operation
- Supports metadata and expiration

## Proposal

Create `@adobe/helix-shared-edge-kv` package providing unified KV store interface for both platforms.

### API Design

```javascript
class UnifiedKVStore {
async get(key, options = {})
async put(key, value, options = {})
async delete(key)
async list(options = {}) // Cloudflare only
}
```

### Platform Adapters

- **FastlyKVAdapter**: Wraps `fastly:kv-store`
- **CloudflareKVAdapter**: Wraps Workers KV binding

### Implementation Pattern

Follow helix-universal adapter pattern (PR #426):
- Platform detection
- Unified interface with graceful degradation
- Feature detection for platform-specific capabilities (list, metadata)

## References

- API Analysis: https://github.com/adobe/helix-deploy-plugin-edge/blob/main/docs/api-unification/cache-storage.md#fastlykv-store
- PR #77: https://github.com/adobe/helix-deploy-plugin-edge/pull/77
- Comment: https://github.com/adobe/helix-deploy-plugin-edge/pull/77#issuecomment-3554569809

Contributor guide

Open the contributing guide

Research direction

Start by reading docs/api-unification/cache-storage.md and the API differences documented in PR adobe/helix-deploy-plugin-edge#77, then review the helix-universal adapter pattern referenced as PR #426. Done means a package exposes the proposed unified get, put, delete, and list interface through Fastly and Cloudflare adapters, with graceful handling of platform-specific capabilities.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.