@oncely/upstash 1.0.0

package/README.md

@@ -0,0 +1,165 @@
+# @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
+
+```typescript
+// 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
+
+```typescript
+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:
+
+```typescript
+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

package/dist/index.cjs

@@ -0,0 +1,154 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UpstashStorage: () => UpstashStorage,
+  upstash: () => upstash
+});
+module.exports = __toCommonJS(index_exports);
+var import_redis = require("@upstash/redis");
+var UpstashStorage = class {
+  client;
+  keyPrefix;
+  constructor(options) {
+    this.client = options._client;
+    this.keyPrefix = options.keyPrefix;
+  }
+  key(id) {
+    return `${this.keyPrefix}${id}`;
+  }
+  async acquire(key, hash, ttlMs) {
+    const fullKey = this.key(key);
+    const now = Date.now();
+    const record = {
+      status: "in_progress",
+      hash,
+      startedAt: now
+    };
+    const acquired = await this.client.set(fullKey, record, {
+      nx: true,
+      px: ttlMs
+    });
+    if (acquired === "OK") {
+      return { status: "acquired" };
+    }
+    const existing = await this.client.get(fullKey);
+    if (!existing) {
+      const retryAcquired = await this.client.set(fullKey, record, {
+        nx: true,
+        px: ttlMs
+      });
+      return retryAcquired === "OK" ? { status: "acquired" } : { status: "conflict", startedAt: now };
+    }
+    if (typeof existing !== "object" || !existing.status) {
+      await this.client.del(fullKey);
+      const retryAcquired = await this.client.set(fullKey, record, {
+        nx: true,
+        px: ttlMs
+      });
+      return retryAcquired === "OK" ? { status: "acquired" } : { status: "conflict", startedAt: now };
+    }
+    if (existing.status === "completed") {
+      if (hash !== null && existing.hash !== null && hash !== existing.hash) {
+        return {
+          status: "mismatch",
+          existingHash: existing.hash,
+          providedHash: hash
+        };
+      }
+      return {
+        status: "hit",
+        response: {
+          data: existing.data,
+          createdAt: existing.createdAt ?? existing.startedAt,
+          hash: existing.hash
+        }
+      };
+    }
+    if (hash !== null && existing.hash !== null && hash !== existing.hash) {
+      return {
+        status: "mismatch",
+        existingHash: existing.hash,
+        providedHash: hash
+      };
+    }
+    return { status: "conflict", startedAt: existing.startedAt };
+  }
+  async save(key, response) {
+    const fullKey = this.key(key);
+    const existing = await this.client.get(fullKey);
+    if (!existing) return;
+    const ttl = await this.client.pttl(fullKey);
+    if (ttl <= 0) return;
+    const record = {
+      status: "completed",
+      hash: response.hash,
+      data: response.data,
+      createdAt: response.createdAt,
+      startedAt: existing.startedAt ?? Date.now()
+    };
+    await this.client.set(fullKey, record, { px: ttl });
+  }
+  async release(key) {
+    await this.client.del(this.key(key));
+  }
+  async delete(key) {
+    await this.client.del(this.key(key));
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.keyPrefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+};
+function upstash(options) {
+  const keyPrefix = options?.keyPrefix ?? "oncely:";
+  if (options?.client) {
+    return new UpstashStorage({
+      keyPrefix,
+      _client: options.client
+    });
+  }
+  const url = options?.url ?? process.env.ONCELY_UPSTASH_REST_URL;
+  const token = options?.token ?? process.env.ONCELY_UPSTASH_REST_TOKEN;
+  if (!url) {
+    throw new Error(
+      "Upstash URL not provided. Set ONCELY_UPSTASH_REST_URL environment variable or pass url option."
+    );
+  }
+  if (!token) {
+    throw new Error(
+      "Upstash token not provided. Set ONCELY_UPSTASH_REST_TOKEN environment variable or pass token option."
+    );
+  }
+  const client = new import_redis.Redis({ url, token });
+  return new UpstashStorage({
+    keyPrefix,
+    _client: client
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UpstashStorage,
+  upstash
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @oncely/upstash - Upstash Redis adapter for oncely idempotency\n *\n * Built for serverless and edge environments - HTTP-based, no connections required.\n *\n * @example\n * ```typescript\n * import { upstash } from '@oncely/upstash';\n *\n * // Auto-discover from ONCELY_UPSTASH_REST_URL and ONCELY_UPSTASH_REST_TOKEN\n * const storage = upstash();\n *\n * // Or configure explicitly\n * const storage = upstash({\n *   url: 'https://your-redis.upstash.io',\n *   token: 'your-token',\n * });\n * ```\n */\n\nimport type { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';\nimport { Redis } from '@upstash/redis';\n\n/**\n * Internal record structure stored in Upstash\n */\ninterface StoredRecord {\n  status: 'in_progress' | 'completed';\n  hash: string | null;\n  data?: unknown;\n  createdAt?: number;\n  startedAt: number;\n}\n\n/**\n * Options for creating an Upstash storage adapter\n */\nexport interface UpstashOptions {\n  /** Upstash REST URL (defaults to ONCELY_UPSTASH_REST_URL) */\n  url?: string;\n  /** Upstash REST token (defaults to ONCELY_UPSTASH_REST_TOKEN) */\n  token?: string;\n  /** Existing @upstash/redis client instance */\n  client?: Redis;\n  /** Key prefix for all stored data (default: 'oncely:') */\n  keyPrefix?: string;\n}\n\n/**\n * Upstash Redis storage adapter for oncely idempotency.\n *\n * Implements the StorageAdapter interface using Upstash's HTTP-based Redis client,\n * making it ideal for serverless and edge environments.\n */\nexport class UpstashStorage implements StorageAdapter {\n  private readonly client: Redis;\n  private readonly keyPrefix: string;\n\n  constructor(options: { keyPrefix: string; _client: Redis }) {\n    this.client = options._client;\n    this.keyPrefix = options.keyPrefix;\n  }\n\n  private key(id: string): string {\n    return `${this.keyPrefix}${id}`;\n  }\n\n  async acquire(key: string, hash: string | null, ttlMs: number): Promise<AcquireResult> {\n    const fullKey = this.key(key);\n    const now = Date.now();\n\n    // Atomic acquire: Try SET NX first (only set if not exists)\n    // This prevents race conditions where two requests both think they acquired\n    const record: StoredRecord = {\n      status: 'in_progress',\n      hash,\n      startedAt: now,\n    };\n\n    const acquired = await this.client.set(fullKey, record, {\n      nx: true,\n      px: ttlMs,\n    });\n\n    // If we acquired the lock, we're done\n    if (acquired === 'OK') {\n      return { status: 'acquired' };\n    }\n\n    // Lock not acquired - key exists. Now fetch to determine why.\n    const existing = await this.client.get<StoredRecord>(fullKey);\n\n    // Key expired or was deleted between SET NX and GET - try again\n    if (!existing) {\n      const retryAcquired = await this.client.set(fullKey, record, {\n        nx: true,\n        px: ttlMs,\n      });\n      return retryAcquired === 'OK'\n        ? { status: 'acquired' }\n        : { status: 'conflict', startedAt: now };\n    }\n\n    // Validate it's a proper record\n    if (typeof existing !== 'object' || !existing.status) {\n      // Corrupted data, delete and retry\n      await this.client.del(fullKey);\n      const retryAcquired = await this.client.set(fullKey, record, {\n        nx: true,\n        px: ttlMs,\n      });\n      return retryAcquired === 'OK'\n        ? { status: 'acquired' }\n        : { status: 'conflict', startedAt: now };\n    }\n\n    // Check for completed response (cache hit)\n    if (existing.status === 'completed') {\n      // Check hash mismatch\n      if (hash !== null && existing.hash !== null && hash !== existing.hash) {\n        return {\n          status: 'mismatch',\n          existingHash: existing.hash,\n          providedHash: hash,\n        };\n      }\n\n      // Return cached response\n      return {\n        status: 'hit',\n        response: {\n          data: existing.data,\n          createdAt: existing.createdAt ?? existing.startedAt,\n          hash: existing.hash,\n        },\n      };\n    }\n\n    // Status is 'in_progress' - another request is processing\n    // Check hash mismatch even for in-progress requests\n    if (hash !== null && existing.hash !== null && hash !== existing.hash) {\n      return {\n        status: 'mismatch',\n        existingHash: existing.hash,\n        providedHash: hash,\n      };\n    }\n\n    return { status: 'conflict', startedAt: existing.startedAt };\n  }\n\n  async save(key: string, response: StoredResponse): Promise<void> {\n    const fullKey = this.key(key);\n\n    // Get existing record to preserve TTL\n    const existing = await this.client.get<StoredRecord>(fullKey);\n    if (!existing) return;\n\n    // Get remaining TTL\n    const ttl = await this.client.pttl(fullKey);\n    if (ttl <= 0) return;\n\n    const record: StoredRecord = {\n      status: 'completed',\n      hash: response.hash,\n      data: response.data,\n      createdAt: response.createdAt,\n      startedAt: existing.startedAt ?? Date.now(),\n    };\n\n    await this.client.set(fullKey, record, { px: ttl });\n  }\n\n  async release(key: string): Promise<void> {\n    await this.client.del(this.key(key));\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del(this.key(key));\n  }\n\n  async clear(): Promise<void> {\n    // Note: KEYS is not recommended for production with large datasets\n    // Consider using SCAN in production environments\n    const keys = await this.client.keys(`${this.keyPrefix}*`);\n    if (keys.length > 0) {\n      await this.client.del(...keys);\n    }\n  }\n}\n\n/**\n * Create an Upstash storage adapter.\n *\n * @param options - Configuration options or URL string\n * @returns UpstashStorage instance\n *\n * @example\n * ```typescript\n * // Auto-discover from environment\n * const storage = upstash();\n *\n * // With explicit config\n * const storage = upstash({\n *   url: 'https://your-redis.upstash.io',\n *   token: 'your-token',\n * });\n *\n * // With existing client\n * const storage = upstash({ client: existingClient });\n * ```\n */\nexport function upstash(options?: UpstashOptions): UpstashStorage {\n  const keyPrefix = options?.keyPrefix ?? 'oncely:';\n\n  if (options?.client) {\n    return new UpstashStorage({\n      keyPrefix,\n      _client: options.client,\n    });\n  }\n\n  // Get URL and token from options or environment\n  const url = options?.url ?? process.env.ONCELY_UPSTASH_REST_URL;\n  const token = options?.token ?? process.env.ONCELY_UPSTASH_REST_TOKEN;\n\n  if (!url) {\n    throw new Error(\n      'Upstash URL not provided. Set ONCELY_UPSTASH_REST_URL environment variable or pass url option.'\n    );\n  }\n\n  if (!token) {\n    throw new Error(\n      'Upstash token not provided. Set ONCELY_UPSTASH_REST_TOKEN environment variable or pass token option.'\n    );\n  }\n\n  const client = new Redis({ url, token });\n\n  return new UpstashStorage({\n    keyPrefix,\n    _client: client,\n  });\n}\n\n// Re-export types for consumers\nexport type { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,mBAAsB;AAiCf,IAAM,iBAAN,MAA+C;AAAA,EACnC;AAAA,EACA;AAAA,EAEjB,YAAY,SAAgD;AAC1D,SAAK,SAAS,QAAQ;AACtB,SAAK,YAAY,QAAQ;AAAA,EAC3B;AAAA,EAEQ,IAAI,IAAoB;AAC9B,WAAO,GAAG,KAAK,SAAS,GAAG,EAAE;AAAA,EAC/B;AAAA,EAEA,MAAM,QAAQ,KAAa,MAAqB,OAAuC;AACrF,UAAM,UAAU,KAAK,IAAI,GAAG;AAC5B,UAAM,MAAM,KAAK,IAAI;AAIrB,UAAM,SAAuB;AAAA,MAC3B,QAAQ;AAAA,MACR;AAAA,MACA,WAAW;AAAA,IACb;AAEA,UAAM,WAAW,MAAM,KAAK,OAAO,IAAI,SAAS,QAAQ;AAAA,MACtD,IAAI;AAAA,MACJ,IAAI;AAAA,IACN,CAAC;AAGD,QAAI,aAAa,MAAM;AACrB,aAAO,EAAE,QAAQ,WAAW;AAAA,IAC9B;AAGA,UAAM,WAAW,MAAM,KAAK,OAAO,IAAkB,OAAO;AAG5D,QAAI,CAAC,UAAU;AACb,YAAM,gBAAgB,MAAM,KAAK,OAAO,IAAI,SAAS,QAAQ;AAAA,QAC3D,IAAI;AAAA,QACJ,IAAI;AAAA,MACN,CAAC;AACD,aAAO,kBAAkB,OACrB,EAAE,QAAQ,WAAW,IACrB,EAAE,QAAQ,YAAY,WAAW,IAAI;AAAA,IAC3C;AAGA,QAAI,OAAO,aAAa,YAAY,CAAC,SAAS,QAAQ;AAEpD,YAAM,KAAK,OAAO,IAAI,OAAO;AAC7B,YAAM,gBAAgB,MAAM,KAAK,OAAO,IAAI,SAAS,QAAQ;AAAA,QAC3D,IAAI;AAAA,QACJ,IAAI;AAAA,MACN,CAAC;AACD,aAAO,kBAAkB,OACrB,EAAE,QAAQ,WAAW,IACrB,EAAE,QAAQ,YAAY,WAAW,IAAI;AAAA,IAC3C;AAGA,QAAI,SAAS,WAAW,aAAa;AAEnC,UAAI,SAAS,QAAQ,SAAS,SAAS,QAAQ,SAAS,SAAS,MAAM;AACrE,eAAO;AAAA,UACL,QAAQ;AAAA,UACR,cAAc,SAAS;AAAA,UACvB,cAAc;AAAA,QAChB;AAAA,MACF;AAGA,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,UAAU;AAAA,UACR,MAAM,SAAS;AAAA,UACf,WAAW,SAAS,aAAa,SAAS;AAAA,UAC1C,MAAM,SAAS;AAAA,QACjB;AAAA,MACF;AAAA,IACF;AAIA,QAAI,SAAS,QAAQ,SAAS,SAAS,QAAQ,SAAS,SAAS,MAAM;AACrE,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,cAAc,SAAS;AAAA,QACvB,cAAc;AAAA,MAChB;AAAA,IACF;AAEA,WAAO,EAAE,QAAQ,YAAY,WAAW,SAAS,UAAU;AAAA,EAC7D;AAAA,EAEA,MAAM,KAAK,KAAa,UAAyC;AAC/D,UAAM,UAAU,KAAK,IAAI,GAAG;AAG5B,UAAM,WAAW,MAAM,KAAK,OAAO,IAAkB,OAAO;AAC5D,QAAI,CAAC,SAAU;AAGf,UAAM,MAAM,MAAM,KAAK,OAAO,KAAK,OAAO;AAC1C,QAAI,OAAO,EAAG;AAEd,UAAM,SAAuB;AAAA,MAC3B,QAAQ;AAAA,MACR,MAAM,SAAS;AAAA,MACf,MAAM,SAAS;AAAA,MACf,WAAW,SAAS;AAAA,MACpB,WAAW,SAAS,aAAa,KAAK,IAAI;AAAA,IAC5C;AAEA,UAAM,KAAK,OAAO,IAAI,SAAS,QAAQ,EAAE,IAAI,IAAI,CAAC;AAAA,EACpD;AAAA,EAEA,MAAM,QAAQ,KAA4B;AACxC,UAAM,KAAK,OAAO,IAAI,KAAK,IAAI,GAAG,CAAC;AAAA,EACrC;AAAA,EAEA,MAAM,OAAO,KAA4B;AACvC,UAAM,KAAK,OAAO,IAAI,KAAK,IAAI,GAAG,CAAC;AAAA,EACrC;AAAA,EAEA,MAAM,QAAuB;AAG3B,UAAM,OAAO,MAAM,KAAK,OAAO,KAAK,GAAG,KAAK,SAAS,GAAG;AACxD,QAAI,KAAK,SAAS,GAAG;AACnB,YAAM,KAAK,OAAO,IAAI,GAAG,IAAI;AAAA,IAC/B;AAAA,EACF;AACF;AAuBO,SAAS,QAAQ,SAA0C;AAChE,QAAM,YAAY,SAAS,aAAa;AAExC,MAAI,SAAS,QAAQ;AACnB,WAAO,IAAI,eAAe;AAAA,MACxB;AAAA,MACA,SAAS,QAAQ;AAAA,IACnB,CAAC;AAAA,EACH;AAGA,QAAM,MAAM,SAAS,OAAO,QAAQ,IAAI;AACxC,QAAM,QAAQ,SAAS,SAAS,QAAQ,IAAI;AAE5C,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,OAAO;AACV,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,SAAS,IAAI,mBAAM,EAAE,KAAK,MAAM,CAAC;AAEvC,SAAO,IAAI,eAAe;AAAA,IACxB;AAAA,IACA,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+import { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';
+export { AcquireResult, StorageAdapter, StoredResponse } from '@oncely/core';
+import { Redis } from '@upstash/redis';
+
+/**
+ * @oncely/upstash - Upstash Redis adapter for oncely idempotency
+ *
+ * Built for serverless and edge environments - HTTP-based, no connections required.
+ *
+ * @example
+ * ```typescript
+ * import { upstash } from '@oncely/upstash';
+ *
+ * // Auto-discover from ONCELY_UPSTASH_REST_URL and ONCELY_UPSTASH_REST_TOKEN
+ * const storage = upstash();
+ *
+ * // Or configure explicitly
+ * const storage = upstash({
+ *   url: 'https://your-redis.upstash.io',
+ *   token: 'your-token',
+ * });
+ * ```
+ */
+
+/**
+ * Options for creating an Upstash storage adapter
+ */
+interface UpstashOptions {
+    /** Upstash REST URL (defaults to ONCELY_UPSTASH_REST_URL) */
+    url?: string;
+    /** Upstash REST token (defaults to ONCELY_UPSTASH_REST_TOKEN) */
+    token?: string;
+    /** Existing @upstash/redis client instance */
+    client?: Redis;
+    /** Key prefix for all stored data (default: 'oncely:') */
+    keyPrefix?: string;
+}
+/**
+ * Upstash Redis storage adapter for oncely idempotency.
+ *
+ * Implements the StorageAdapter interface using Upstash's HTTP-based Redis client,
+ * making it ideal for serverless and edge environments.
+ */
+declare class UpstashStorage implements StorageAdapter {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(options: {
+        keyPrefix: string;
+        _client: Redis;
+    });
+    private key;
+    acquire(key: string, hash: string | null, ttlMs: number): Promise<AcquireResult>;
+    save(key: string, response: StoredResponse): Promise<void>;
+    release(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Create an Upstash storage adapter.
+ *
+ * @param options - Configuration options or URL string
+ * @returns UpstashStorage instance
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover from environment
+ * const storage = upstash();
+ *
+ * // With explicit config
+ * const storage = upstash({
+ *   url: 'https://your-redis.upstash.io',
+ *   token: 'your-token',
+ * });
+ *
+ * // With existing client
+ * const storage = upstash({ client: existingClient });
+ * ```
+ */
+declare function upstash(options?: UpstashOptions): UpstashStorage;
+
+export { type UpstashOptions, UpstashStorage, upstash };

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';
+export { AcquireResult, StorageAdapter, StoredResponse } from '@oncely/core';
+import { Redis } from '@upstash/redis';
+
+/**
+ * @oncely/upstash - Upstash Redis adapter for oncely idempotency
+ *
+ * Built for serverless and edge environments - HTTP-based, no connections required.
+ *
+ * @example
+ * ```typescript
+ * import { upstash } from '@oncely/upstash';
+ *
+ * // Auto-discover from ONCELY_UPSTASH_REST_URL and ONCELY_UPSTASH_REST_TOKEN
+ * const storage = upstash();
+ *
+ * // Or configure explicitly
+ * const storage = upstash({
+ *   url: 'https://your-redis.upstash.io',
+ *   token: 'your-token',
+ * });
+ * ```
+ */
+
+/**
+ * Options for creating an Upstash storage adapter
+ */
+interface UpstashOptions {
+    /** Upstash REST URL (defaults to ONCELY_UPSTASH_REST_URL) */
+    url?: string;
+    /** Upstash REST token (defaults to ONCELY_UPSTASH_REST_TOKEN) */
+    token?: string;
+    /** Existing @upstash/redis client instance */
+    client?: Redis;
+    /** Key prefix for all stored data (default: 'oncely:') */
+    keyPrefix?: string;
+}
+/**
+ * Upstash Redis storage adapter for oncely idempotency.
+ *
+ * Implements the StorageAdapter interface using Upstash's HTTP-based Redis client,
+ * making it ideal for serverless and edge environments.
+ */
+declare class UpstashStorage implements StorageAdapter {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(options: {
+        keyPrefix: string;
+        _client: Redis;
+    });
+    private key;
+    acquire(key: string, hash: string | null, ttlMs: number): Promise<AcquireResult>;
+    save(key: string, response: StoredResponse): Promise<void>;
+    release(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Create an Upstash storage adapter.
+ *
+ * @param options - Configuration options or URL string
+ * @returns UpstashStorage instance
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover from environment
+ * const storage = upstash();
+ *
+ * // With explicit config
+ * const storage = upstash({
+ *   url: 'https://your-redis.upstash.io',
+ *   token: 'your-token',
+ * });
+ *
+ * // With existing client
+ * const storage = upstash({ client: existingClient });
+ * ```
+ */
+declare function upstash(options?: UpstashOptions): UpstashStorage;
+
+export { type UpstashOptions, UpstashStorage, upstash };

package/dist/index.js

@@ -0,0 +1,128 @@
+// src/index.ts
+import { Redis } from "@upstash/redis";
+var UpstashStorage = class {
+  client;
+  keyPrefix;
+  constructor(options) {
+    this.client = options._client;
+    this.keyPrefix = options.keyPrefix;
+  }
+  key(id) {
+    return `${this.keyPrefix}${id}`;
+  }
+  async acquire(key, hash, ttlMs) {
+    const fullKey = this.key(key);
+    const now = Date.now();
+    const record = {
+      status: "in_progress",
+      hash,
+      startedAt: now
+    };
+    const acquired = await this.client.set(fullKey, record, {
+      nx: true,
+      px: ttlMs
+    });
+    if (acquired === "OK") {
+      return { status: "acquired" };
+    }
+    const existing = await this.client.get(fullKey);
+    if (!existing) {
+      const retryAcquired = await this.client.set(fullKey, record, {
+        nx: true,
+        px: ttlMs
+      });
+      return retryAcquired === "OK" ? { status: "acquired" } : { status: "conflict", startedAt: now };
+    }
+    if (typeof existing !== "object" || !existing.status) {
+      await this.client.del(fullKey);
+      const retryAcquired = await this.client.set(fullKey, record, {
+        nx: true,
+        px: ttlMs
+      });
+      return retryAcquired === "OK" ? { status: "acquired" } : { status: "conflict", startedAt: now };
+    }
+    if (existing.status === "completed") {
+      if (hash !== null && existing.hash !== null && hash !== existing.hash) {
+        return {
+          status: "mismatch",
+          existingHash: existing.hash,
+          providedHash: hash
+        };
+      }
+      return {
+        status: "hit",
+        response: {
+          data: existing.data,
+          createdAt: existing.createdAt ?? existing.startedAt,
+          hash: existing.hash
+        }
+      };
+    }
+    if (hash !== null && existing.hash !== null && hash !== existing.hash) {
+      return {
+        status: "mismatch",
+        existingHash: existing.hash,
+        providedHash: hash
+      };
+    }
+    return { status: "conflict", startedAt: existing.startedAt };
+  }
+  async save(key, response) {
+    const fullKey = this.key(key);
+    const existing = await this.client.get(fullKey);
+    if (!existing) return;
+    const ttl = await this.client.pttl(fullKey);
+    if (ttl <= 0) return;
+    const record = {
+      status: "completed",
+      hash: response.hash,
+      data: response.data,
+      createdAt: response.createdAt,
+      startedAt: existing.startedAt ?? Date.now()
+    };
+    await this.client.set(fullKey, record, { px: ttl });
+  }
+  async release(key) {
+    await this.client.del(this.key(key));
+  }
+  async delete(key) {
+    await this.client.del(this.key(key));
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.keyPrefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+};
+function upstash(options) {
+  const keyPrefix = options?.keyPrefix ?? "oncely:";
+  if (options?.client) {
+    return new UpstashStorage({
+      keyPrefix,
+      _client: options.client
+    });
+  }
+  const url = options?.url ?? process.env.ONCELY_UPSTASH_REST_URL;
+  const token = options?.token ?? process.env.ONCELY_UPSTASH_REST_TOKEN;
+  if (!url) {
+    throw new Error(
+      "Upstash URL not provided. Set ONCELY_UPSTASH_REST_URL environment variable or pass url option."
+    );
+  }
+  if (!token) {
+    throw new Error(
+      "Upstash token not provided. Set ONCELY_UPSTASH_REST_TOKEN environment variable or pass token option."
+    );
+  }
+  const client = new Redis({ url, token });
+  return new UpstashStorage({
+    keyPrefix,
+    _client: client
+  });
+}
+export {
+  UpstashStorage,
+  upstash
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @oncely/upstash - Upstash Redis adapter for oncely idempotency\n *\n * Built for serverless and edge environments - HTTP-based, no connections required.\n *\n * @example\n * ```typescript\n * import { upstash } from '@oncely/upstash';\n *\n * // Auto-discover from ONCELY_UPSTASH_REST_URL and ONCELY_UPSTASH_REST_TOKEN\n * const storage = upstash();\n *\n * // Or configure explicitly\n * const storage = upstash({\n *   url: 'https://your-redis.upstash.io',\n *   token: 'your-token',\n * });\n * ```\n */\n\nimport type { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';\nimport { Redis } from '@upstash/redis';\n\n/**\n * Internal record structure stored in Upstash\n */\ninterface StoredRecord {\n  status: 'in_progress' | 'completed';\n  hash: string | null;\n  data?: unknown;\n  createdAt?: number;\n  startedAt: number;\n}\n\n/**\n * Options for creating an Upstash storage adapter\n */\nexport interface UpstashOptions {\n  /** Upstash REST URL (defaults to ONCELY_UPSTASH_REST_URL) */\n  url?: string;\n  /** Upstash REST token (defaults to ONCELY_UPSTASH_REST_TOKEN) */\n  token?: string;\n  /** Existing @upstash/redis client instance */\n  client?: Redis;\n  /** Key prefix for all stored data (default: 'oncely:') */\n  keyPrefix?: string;\n}\n\n/**\n * Upstash Redis storage adapter for oncely idempotency.\n *\n * Implements the StorageAdapter interface using Upstash's HTTP-based Redis client,\n * making it ideal for serverless and edge environments.\n */\nexport class UpstashStorage implements StorageAdapter {\n  private readonly client: Redis;\n  private readonly keyPrefix: string;\n\n  constructor(options: { keyPrefix: string; _client: Redis }) {\n    this.client = options._client;\n    this.keyPrefix = options.keyPrefix;\n  }\n\n  private key(id: string): string {\n    return `${this.keyPrefix}${id}`;\n  }\n\n  async acquire(key: string, hash: string | null, ttlMs: number): Promise<AcquireResult> {\n    const fullKey = this.key(key);\n    const now = Date.now();\n\n    // Atomic acquire: Try SET NX first (only set if not exists)\n    // This prevents race conditions where two requests both think they acquired\n    const record: StoredRecord = {\n      status: 'in_progress',\n      hash,\n      startedAt: now,\n    };\n\n    const acquired = await this.client.set(fullKey, record, {\n      nx: true,\n      px: ttlMs,\n    });\n\n    // If we acquired the lock, we're done\n    if (acquired === 'OK') {\n      return { status: 'acquired' };\n    }\n\n    // Lock not acquired - key exists. Now fetch to determine why.\n    const existing = await this.client.get<StoredRecord>(fullKey);\n\n    // Key expired or was deleted between SET NX and GET - try again\n    if (!existing) {\n      const retryAcquired = await this.client.set(fullKey, record, {\n        nx: true,\n        px: ttlMs,\n      });\n      return retryAcquired === 'OK'\n        ? { status: 'acquired' }\n        : { status: 'conflict', startedAt: now };\n    }\n\n    // Validate it's a proper record\n    if (typeof existing !== 'object' || !existing.status) {\n      // Corrupted data, delete and retry\n      await this.client.del(fullKey);\n      const retryAcquired = await this.client.set(fullKey, record, {\n        nx: true,\n        px: ttlMs,\n      });\n      return retryAcquired === 'OK'\n        ? { status: 'acquired' }\n        : { status: 'conflict', startedAt: now };\n    }\n\n    // Check for completed response (cache hit)\n    if (existing.status === 'completed') {\n      // Check hash mismatch\n      if (hash !== null && existing.hash !== null && hash !== existing.hash) {\n        return {\n          status: 'mismatch',\n          existingHash: existing.hash,\n          providedHash: hash,\n        };\n      }\n\n      // Return cached response\n      return {\n        status: 'hit',\n        response: {\n          data: existing.data,\n          createdAt: existing.createdAt ?? existing.startedAt,\n          hash: existing.hash,\n        },\n      };\n    }\n\n    // Status is 'in_progress' - another request is processing\n    // Check hash mismatch even for in-progress requests\n    if (hash !== null && existing.hash !== null && hash !== existing.hash) {\n      return {\n        status: 'mismatch',\n        existingHash: existing.hash,\n        providedHash: hash,\n      };\n    }\n\n    return { status: 'conflict', startedAt: existing.startedAt };\n  }\n\n  async save(key: string, response: StoredResponse): Promise<void> {\n    const fullKey = this.key(key);\n\n    // Get existing record to preserve TTL\n    const existing = await this.client.get<StoredRecord>(fullKey);\n    if (!existing) return;\n\n    // Get remaining TTL\n    const ttl = await this.client.pttl(fullKey);\n    if (ttl <= 0) return;\n\n    const record: StoredRecord = {\n      status: 'completed',\n      hash: response.hash,\n      data: response.data,\n      createdAt: response.createdAt,\n      startedAt: existing.startedAt ?? Date.now(),\n    };\n\n    await this.client.set(fullKey, record, { px: ttl });\n  }\n\n  async release(key: string): Promise<void> {\n    await this.client.del(this.key(key));\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del(this.key(key));\n  }\n\n  async clear(): Promise<void> {\n    // Note: KEYS is not recommended for production with large datasets\n    // Consider using SCAN in production environments\n    const keys = await this.client.keys(`${this.keyPrefix}*`);\n    if (keys.length > 0) {\n      await this.client.del(...keys);\n    }\n  }\n}\n\n/**\n * Create an Upstash storage adapter.\n *\n * @param options - Configuration options or URL string\n * @returns UpstashStorage instance\n *\n * @example\n * ```typescript\n * // Auto-discover from environment\n * const storage = upstash();\n *\n * // With explicit config\n * const storage = upstash({\n *   url: 'https://your-redis.upstash.io',\n *   token: 'your-token',\n * });\n *\n * // With existing client\n * const storage = upstash({ client: existingClient });\n * ```\n */\nexport function upstash(options?: UpstashOptions): UpstashStorage {\n  const keyPrefix = options?.keyPrefix ?? 'oncely:';\n\n  if (options?.client) {\n    return new UpstashStorage({\n      keyPrefix,\n      _client: options.client,\n    });\n  }\n\n  // Get URL and token from options or environment\n  const url = options?.url ?? process.env.ONCELY_UPSTASH_REST_URL;\n  const token = options?.token ?? process.env.ONCELY_UPSTASH_REST_TOKEN;\n\n  if (!url) {\n    throw new Error(\n      'Upstash URL not provided. Set ONCELY_UPSTASH_REST_URL environment variable or pass url option.'\n    );\n  }\n\n  if (!token) {\n    throw new Error(\n      'Upstash token not provided. Set ONCELY_UPSTASH_REST_TOKEN environment variable or pass token option.'\n    );\n  }\n\n  const client = new Redis({ url, token });\n\n  return new UpstashStorage({\n    keyPrefix,\n    _client: client,\n  });\n}\n\n// Re-export types for consumers\nexport type { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@oncely/upstash",
+  "version": "1.0.0",
+  "description": "Upstash Redis adapter for oncely idempotency",
+  "author": "stacks0x",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stacks0x/oncely.git",
+    "directory": "packages/upstash"
+  },
+  "keywords": [
+    "oncely",
+    "idempotency",
+    "idempotent",
+    "upstash",
+    "redis",
+    "serverless",
+    "edge",
+    "vercel"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "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"
+  },
+  "devDependencies": {
+    "@oncely/core": "workspace:*",
+    "@upstash/redis": "^1.28.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}