npm package: @idempotix/upstash
Description: Upstash Redis adapter for Idempotix idempotency
Author: stacks0x
Latest version: 1.0.5

<p align="center">
  <a href="https://github.com/stacks0x/idempotix"><img src="https://raw.githubusercontent.com/stacks0x/idempotix/main/assets/idempotix.jpg" alt="Idempotix" width="80" /></a>
</p>

# @idempotix/upstash

Upstash Redis adapter for Idempotix. HTTP-based, perfect for serverless and edge.

[![npm version](https://img.shields.io/npm/v/@idempotix/upstash.svg)](https://www.npmjs.com/package/@idempotix/upstash)

## Installation

```bash
npm install @idempotix/core @idempotix/upstash
```

## Quick Start

```typescript
import { upstash } from '@idempotix/upstash';
import { next } from '@idempotix/next';

// From environment variables
export const POST = next({ storage: upstash() })(handler);
```

## Configuration

```typescript
import { upstash } from '@idempotix/upstash';

// From environment variables (IDEMPOTIX_UPSTASH_REST_URL, IDEMPOTIX_UPSTASH_REST_TOKEN)
const storage = upstash();

// With explicit credentials
const storage = upstash({
  url: 'https://your-redis.upstash.io',
  token: 'your-rest-token',
});

// With options
const storage = upstash({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
  keyPrefix: 'myapp:idem:',
});

// With existing @upstash/redis client
import { Redis } from '@upstash/redis';
const client = new Redis({ url: '...', token: '...' });
const storage = upstash({ client });
```

## Environment Variables

| Variable                       | Description                                            |
| ------------------------------ | ------------------------------------------------------ |
| `IDEMPOTIX_UPSTASH_REST_URL`   | Upstash REST endpoint (e.g., `https://xyz.upstash.io`) |
| `IDEMPOTIX_UPSTASH_REST_TOKEN` | Upstash REST token                                     |

## Usage with Next.js App Router

```typescript
// app/api/orders/route.ts
import { next } from '@idempotix/next';
import { upstash } from '@idempotix/upstash';

export const POST = next({ storage: upstash() })(async (req) => {
  const order = await createOrder(await req.json());
  return Response.json(order, { status: 201 });
});
```

## Usage with Next.js Pages Router

```typescript
// pages/api/orders.ts
import { pages } from '@idempotix/next/pages';
import { upstash } from '@idempotix/upstash';

export default pages({ storage: upstash() })(async (req, res) => {
  const order = await createOrder(req.body);
  res.status(201).json(order);
});
```

## Pre-configured Factory

```typescript
// lib/idempotency.ts
import { configure } from '@idempotix/next';
import { upstash } from '@idempotix/upstash';

export const idempotent = configure({
  storage: upstash(),
  ttl: '1h',
});

// app/api/orders/route.ts
import { idempotent } from '@/lib/idempotency';

export const POST = idempotent()(handler);
```

## Vercel KV

Vercel KV is compatible with Upstash. Use the Vercel KV environment variables:

```typescript
const storage = upstash({
  url: process.env.KV_REST_API_URL,
  token: process.env.KV_REST_API_TOKEN,
});
```

## Key Prefix

All keys are prefixed with `Idempotix:` by default. Customize with:

```typescript
const storage = upstash({ keyPrefix: 'myapp:idem:' });
```

## License

MIT