@oncely/upstash

@oncely/upstash

Upstash storage adapter for oncely (edge/serverless compatible).

Installation

npm install @oncely/core @oncely/upstash

Usage

import { upstash, UpstashStorage } from '@oncely/upstash'; import { next } from '@oncely/next';

// From environment variables const storage = upstash();

// With explicit config const storage = upstash({ url: 'https://...', token: '...', });

// Use with Next.js export const POST = next({ storage: upstash() })(handler);

Environment Variables

ONCELY_UPSTASH_REST_URL - Upstash REST URL ONCELY_UPSTASH_REST_TOKEN - Upstash REST token

License

MIT await storage.acquire(key, hash, ttl); // AcquireResult await storage.save(key, response); // void await storage.release(key); // void await storage.delete(key); // void await storage.clear(); // void

## Usage Examples

### Next.js App Router (Edge)

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

export const runtime = 'edge';

const handler = oncely.handler({
  storage: upstash(),
  ttl: 60000,
});

export async function POST(request: Request) {
  return handler(request, async (req) => {
    const body = await req.json();
    const order = await createOrder(body);

    return Response.json(order, { status: 201 });
  });
}

Vercel Serverless Function

// api/checkout.ts
import type { VercelRequest, VercelResponse } from '@vercel/node';
import { oncely } from '@oncely/core';
import { upstash } from '@oncely/upstash';

const storage = upstash();

export default async function handler(req: VercelRequest, res: VercelResponse) {
  const idempotencyKey = req.headers['idempotency-key'] as string;

  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Idempotency-Key required' });
  }

  const result = await storage.acquire(idempotencyKey, null, 60000);

  if (result.status === 'hit') {
    res.setHeader('Idempotency-Replay', 'true');
    return res.json(result.response.data);
  }

  if (result.status === 'conflict') {
    return res.status(409).json({ error: 'Request in progress' });
  }

  try {
    const data = await processCheckout(req.body);
    await storage.save(idempotencyKey, {
      data,
      createdAt: Date.now(),
      hash: null,
    });
    return res.json(data);
  } catch (error) {
    await storage.release(idempotencyKey);
    throw error;
  }
}

Cloudflare Workers

import { oncely } from '@oncely/core';
import { upstash } from '@oncely/upstash';

export interface Env {
  ONCELY_UPSTASH_REST_URL: string;
  ONCELY_UPSTASH_REST_TOKEN: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const storage = upstash({
      url: env.ONCELY_UPSTASH_REST_URL,
      token: env.ONCELY_UPSTASH_REST_TOKEN,
    });

    const handler = oncely.handler({
      storage,
      ttl: 60000,
    });

    return handler(request, async (req) => {
      // Your handler logic
      return new Response(JSON.stringify({ ok: true }));
    });
  },
};

With Regional Endpoints

For lower latency, use Upstash regional endpoints:

const storage = upstash({
  url: process.env.ONCELY_UPSTASH_REST_URL_US_EAST_1,
  token: process.env.ONCELY_UPSTASH_REST_TOKEN,
});

Why Upstash?

Feature	Upstash	Self-hosted Redis
Edge/Serverless	✅ HTTP-based	❌ Requires TCP
Connection pooling	✅ Not needed	⚠️ Required
Cold start	✅ Instant	⚠️ Connection overhead
Scaling	✅ Auto	Manual
Global	✅ Multi-region	Manual setup

License

MIT