@oncely/upstash 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stacks0x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,164 +1,121 @@
 # @oncely/upstash
 
-Upstash storage adapter for oncely (edge/serverless compatible).
+Upstash Redis adapter for oncely. HTTP-based, perfect for serverless and edge.
+
+[![npm version](https://img.shields.io/npm/v/@oncely/upstash.svg)](https://www.npmjs.com/package/@oncely/upstash)
 
 ## Installation
 
+```bash
 npm install @oncely/core @oncely/upstash
+```
 
-## Usage
+## Quick Start
 
-import { upstash, UpstashStorage } from '@oncely/upstash';
+```typescript
+import { upstash } from '@oncely/upstash';
 import { next } from '@oncely/next';
 
 // From environment variables
-const storage = upstash();
+export const POST = next({ storage: upstash() })(handler);
+```
 
-// With explicit config
-const storage = upstash({
-url: 'https://...',
-token: '...',
-});
+## Configuration
 
-// Use with Next.js
-export const POST = next({ storage: upstash() })(handler);
+```typescript
+import { upstash } from '@oncely/upstash';
 
-## Environment Variables
+// From environment variables (ONCELY_UPSTASH_REST_URL, ONCELY_UPSTASH_REST_TOKEN)
+const storage = upstash();
 
-ONCELY_UPSTASH_REST_URL - Upstash REST URL
-ONCELY_UPSTASH_REST_TOKEN - Upstash REST token
+// With explicit credentials
+const storage = upstash({
+  url: 'https://your-redis.upstash.io',
+  token: 'your-rest-token',
+});
 
-## License
+// With options
+const storage = upstash({
+  url: process.env.UPSTASH_REDIS_REST_URL,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN,
+  keyPrefix: 'myapp:idem:',
+});
 
-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
+// With existing @upstash/redis client
+import { Redis } from '@upstash/redis';
+const client = new Redis({ url: '...', token: '...' });
+const storage = upstash({ client });
+```
 
-````
+## Environment Variables
 
-## Usage Examples
+| Variable                    | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `ONCELY_UPSTASH_REST_URL`   | Upstash REST endpoint (e.g., `https://xyz.upstash.io`) |
+| `ONCELY_UPSTASH_REST_TOKEN` | Upstash REST token                                     |
 
-### Next.js App Router (Edge)
+## Usage with Next.js App Router
 
 ```typescript
 // app/api/orders/route.ts
-import { oncely } from '@oncely/core';
+import { next } from '@oncely/next';
 import { upstash } from '@oncely/upstash';
 
-export const runtime = 'edge';
-
-const handler = oncely.handler({
-  storage: upstash(),
-  ttl: 60000,
+export const POST = next({ storage: upstash() })(async (req) => {
+  const order = await createOrder(await req.json());
+  return Response.json(order, { status: 201 });
 });
+```
 
-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
+## Usage with Next.js Pages Router
 
 ```typescript
-// api/checkout.ts
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import { oncely } from '@oncely/core';
+// pages/api/orders.ts
+import { pages } from '@oncely/next/pages';
 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;
-  }
-}
+export default pages({ storage: upstash() })(async (req, res) => {
+  const order = await createOrder(req.body);
+  res.status(201).json(order);
+});
 ```
 
-### Cloudflare Workers
+## Pre-configured Factory
 
 ```typescript
-import { oncely } from '@oncely/core';
+// lib/idempotency.ts
+import { configure } from '@oncely/next';
 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 }));
-    });
-  },
-};
+export const idempotent = configure({
+  storage: upstash(),
+  ttl: '1h',
+});
+
+// app/api/orders/route.ts
+import { idempotent } from '@/lib/idempotency';
+
+export const POST = idempotent()(handler);
 ```
 
-### With Regional Endpoints
+## Vercel KV
 
-For lower latency, use Upstash regional endpoints:
+Vercel KV is compatible with Upstash. Use the Vercel KV environment variables:
 
 ```typescript
 const storage = upstash({
-  url: process.env.ONCELY_UPSTASH_REST_URL_US_EAST_1,
-  token: process.env.ONCELY_UPSTASH_REST_TOKEN,
+  url: process.env.KV_REST_API_URL,
+  token: process.env.KV_REST_API_TOKEN,
 });
 ```
 
-## Why Upstash?
+## Key Prefix
+
+All keys are prefixed with `oncely:` by default. Customize with:
 
-| 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           |
+```typescript
+const storage = upstash({ keyPrefix: 'myapp:idem:' });
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oncely/upstash",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Upstash Redis adapter for oncely idempotency",
   "author": "stacks0x",
   "license": "MIT",
@@ -35,26 +35,26 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
-    "@oncely/core": "workspace:*",
-    "@upstash/redis": "^1.28.0"
+    "@upstash/redis": "^1.28.0",
+    "@oncely/core": "0.2.2"
   },
   "devDependencies": {
-    "@oncely/core": "workspace:*",
     "@upstash/redis": "^1.28.0",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "@oncely/core": "0.2.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
   }
-}
+}