@farcaster/snap-upstash 0.0.0-canary-20260402031100

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { type SnapFunction } from "@farcaster/snap";
+export type WithUpstashOptions = {
+    lockAcquireTimeoutMs?: number;
+    lockLeaseDurationMs?: number;
+};
+/**
+ * Wraps a SnapFunction and injects an Upstash Redis-backed data store into
+ * the context.
+ */
+export declare function withUpstash(snapFn: SnapFunction, options?: WithUpstashOptions): SnapFunction;

package/dist/index.js

@@ -0,0 +1,71 @@
+import { Redis } from "@upstash/redis";
+import { Lock } from "@upstash/lock";
+const DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS = 5000;
+const DEFAULT_LOCK_LEASE_DURATION_MS = 1000;
+const LOCK_KEY = "snap:lock";
+const LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Wraps a SnapFunction and injects an Upstash Redis-backed data store into
+ * the context.
+ */
+export function withUpstash(snapFn, options) {
+    const url = process.env.UPSTASH_REDIS_REST_URL || process.env.KV_REST_API_URL;
+    const token = process.env.UPSTASH_REDIS_REST_TOKEN || process.env.KV_REST_API_TOKEN;
+    if (!url || !token) {
+        console.warn("missing env vars -- skipping Upstash data store setup");
+        return snapFn;
+    }
+    const redis = new Redis({ url, token });
+    const acquireTimeoutMs = Math.max(1, options?.lockAcquireTimeoutMs ?? DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS);
+    const leaseDurationMs = Math.max(1, options?.lockLeaseDurationMs ?? DEFAULT_LOCK_LEASE_DURATION_MS);
+    const ops = {
+        async get(key) {
+            return redis.get(key);
+        },
+        async set(key, value) {
+            await redis.set(key, value);
+        },
+    };
+    const store = {
+        ...ops,
+        async withLock(fn) {
+            const lock = new Lock({
+                id: LOCK_KEY,
+                redis,
+                lease: leaseDurationMs,
+                retry: {
+                    attempts: Math.ceil(acquireTimeoutMs / LOCK_RETRY_DELAY_MS),
+                    delay: LOCK_RETRY_DELAY_MS,
+                },
+            });
+            if (!(await lock.acquire())) {
+                throw new Error(`snap-upstash: failed to acquire lock within ${acquireTimeoutMs}ms`);
+            }
+            let fnError;
+            try {
+                return await fn(ops);
+            }
+            catch (err) {
+                fnError = err;
+                throw err;
+            }
+            finally {
+                try {
+                    await lock.release();
+                }
+                catch (releaseError) {
+                    if (!fnError) {
+                        // If the critical section succeeded but releasing the lock failed,
+                        // propagate the release error.
+                        throw releaseError;
+                    }
+                    // If both the critical section and lock release failed, log the
+                    // release error and preserve the original error from fn(ops).
+                    // eslint-disable-next-line no-console
+                    console.error("snap-upstash: failed to release lock", releaseError);
+                }
+            }
+        },
+    };
+    return (ctx) => snapFn({ ...ctx, data: store });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@farcaster/snap-upstash",
+  "version": "0.0.0-canary-20260402031100",
+  "description": "Upstash Redis data store adapter for Farcaster Snaps",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farcasterxyz/snap.git",
+    "directory": "pkgs/upstash"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@upstash/lock": "^0.2.1",
+    "@upstash/redis": "^1.37.0",
+    "@farcaster/snap": "0.0.0-canary-20260402031100"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias --resolve-full-paths --resolve-full-extension .js",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+import { Redis } from "@upstash/redis";
+import { Lock } from "@upstash/lock";
+import {
+  type DataStoreValue,
+  type SnapDataStore,
+  type SnapDataStoreOperations,
+  type SnapFunction,
+} from "@farcaster/snap";
+
+export type WithUpstashOptions = {
+  lockAcquireTimeoutMs?: number;
+  lockLeaseDurationMs?: number;
+};
+
+const DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS = 5_000;
+const DEFAULT_LOCK_LEASE_DURATION_MS = 1_000;
+const LOCK_KEY = "snap:lock";
+const LOCK_RETRY_DELAY_MS = 50;
+
+/**
+ * Wraps a SnapFunction and injects an Upstash Redis-backed data store into
+ * the context.
+ */
+export function withUpstash(
+  snapFn: SnapFunction,
+  options?: WithUpstashOptions,
+): SnapFunction {
+  const url = process.env.UPSTASH_REDIS_REST_URL || process.env.KV_REST_API_URL;
+  const token =
+    process.env.UPSTASH_REDIS_REST_TOKEN || process.env.KV_REST_API_TOKEN;
+
+  if (!url || !token) {
+    console.warn("missing env vars -- skipping Upstash data store setup");
+    return snapFn;
+  }
+
+  const redis = new Redis({ url, token });
+
+  const acquireTimeoutMs = Math.max(
+    1,
+    options?.lockAcquireTimeoutMs ?? DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS,
+  );
+  const leaseDurationMs = Math.max(
+    1,
+    options?.lockLeaseDurationMs ?? DEFAULT_LOCK_LEASE_DURATION_MS,
+  );
+
+  const ops: SnapDataStoreOperations = {
+    async get(key: string): Promise<DataStoreValue | null> {
+      return redis.get<DataStoreValue>(key);
+    },
+    async set(key: string, value: DataStoreValue): Promise<void> {
+      await redis.set(key, value);
+    },
+  };
+
+  const store: SnapDataStore = {
+    ...ops,
+    async withLock<T>(
+      fn: (store: SnapDataStoreOperations) => Promise<T>,
+    ): Promise<T> {
+      const lock = new Lock({
+        id: LOCK_KEY,
+        redis,
+        lease: leaseDurationMs,
+        retry: {
+          attempts: Math.ceil(acquireTimeoutMs / LOCK_RETRY_DELAY_MS),
+          delay: LOCK_RETRY_DELAY_MS,
+        },
+      });
+
+      if (!(await lock.acquire())) {
+        throw new Error(
+          `snap-upstash: failed to acquire lock within ${acquireTimeoutMs}ms`,
+        );
+      }
+
+      let fnError: unknown;
+      try {
+        return await fn(ops);
+      } catch (err) {
+        fnError = err;
+        throw err;
+      } finally {
+        try {
+          await lock.release();
+        } catch (releaseError) {
+          if (!fnError) {
+            // If the critical section succeeded but releasing the lock failed,
+            // propagate the release error.
+            throw releaseError;
+          }
+          // If both the critical section and lock release failed, log the
+          // release error and preserve the original error from fn(ops).
+          // eslint-disable-next-line no-console
+          console.error("snap-upstash: failed to release lock", releaseError);
+        }
+      }
+    },
+  };
+
+  return (ctx) => snapFn({ ...ctx, data: store });
+}