@upstash/redis 1.3.0-alpha.1 → 1.3.2-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Upstash, Inc.
+
+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

@@ -19,12 +19,16 @@ It is the only connectionless (HTTP based) Redis client and designed for:
 - WebAssembly
 - and other environments where HTTP is preferred over TCP.
 
-See [the list of APIs](https://docs.upstash.com/features/restapi#rest---redis-api-compatibility) supported.
+See
+[the list of APIs](https://docs.upstash.com/features/restapi#rest---redis-api-compatibility)
+supported.
 
 ## Upgrading from v0.2.0?
 
-Please read the [migration guide](https://github.com/upstash/upstash-redis#migrating-to-v1).
-For further explanation we wrote a [blog post](https://blog.upstash.com/upstash-redis-sdk-v1).
+Please read the
+[migration guide](https://github.com/upstash/upstash-redis#migrating-to-v1). For
+further explanation we wrote a
+[blog post](https://blog.upstash.com/upstash-redis-sdk-v1).
 
 ## Quick Start
 
@@ -40,14 +44,17 @@ Create a new redis database on [upstash](https://console.upstash.com/)
 
 ### Environments
 
-We support various platforms, such as nodejs, cloudflare and fastly.
-Platforms differ slightly when it comes to environment variables and their `fetch` api. Please use the correct import when deploying to special platforms.
+We support various platforms, such as nodejs, cloudflare and fastly. Platforms
+differ slightly when it comes to environment variables and their `fetch` api.
+Please use the correct import when deploying to special platforms.
 
 #### Node.js
 
 Examples: Vercel, Netlify, AWS Lambda
 
-If you are running on nodejs you can set `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` as environment variable and create a redis instance like this:
+If you are running on nodejs you can set `UPSTASH_REDIS_REST_URL` and
+`UPSTASH_REDIS_REST_TOKEN` as environment variable and create a redis instance
+like this:
 
 ```ts
 import { Redis } from "@upstash/redis"
@@ -65,8 +72,9 @@ const redis = Redis.fromEnv()
 
 #### Cloudflare Workers
 
-Cloudflare handles environment variables differently than nodejs.
-Please add `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` using `wrangler secret put ...` or in the cloudflare dashboard.
+Cloudflare handles environment variables differently than nodejs. Please add
+`UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` using
+`wrangler secret put ...` or in the cloudflare dashboard.
 
 Afterwards you can create a redis instance:
 
@@ -92,7 +100,6 @@ export default {
     // ...
   }
 }
-
 ```
 
 - [Code example service worker](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers)
@@ -101,7 +108,10 @@ export default {
 
 #### Fastly
 
-Fastly introduces a concept called [backend](https://developer.fastly.com/reference/api/services/backend/). You need to configure a backend in your `fastly.toml`. An example can be found [here](https://github.com/upstash/upstash-redis/blob/main/examples/fastly/fastly.toml).
+Fastly introduces a concept called
+[backend](https://developer.fastly.com/reference/api/services/backend/). You
+need to configure a backend in your `fastly.toml`. An example can be found
+[here](https://github.com/upstash/upstash-redis/blob/main/examples/fastly/fastly.toml).
 Until the fastly api stabilizes we recommend creating an instance manually:
 
 ```ts
@@ -119,10 +129,11 @@ const redis = new Redis({
 
 ### Working with types
 
-Most commands allow you to provide a type to make working with typescript easier.
+Most commands allow you to provide a type to make working with typescript
+easier.
 
 ```ts
-const data = await redis.get<MyCustomType>("key")
+const data = await redis.get<MyCustomType>("key");
 // data is typed as `MyCustomType`
 ```
 
@@ -130,8 +141,8 @@ const data = await redis.get<MyCustomType>("key")
 
 ### Explicit authentication
 
-The library is no longer automatically trying to load connection secrets from environment variables.
-You must either supply them yourself:
+The library is no longer automatically trying to load connection secrets from
+environment variables. You must either supply them yourself:
 
 ```ts
 import { Redis } from "@upstash/redis"
@@ -146,14 +157,14 @@ Or use one of the static constructors to load from environment variables:
 
 ```ts
 // Nodejs
-import { Redis } from "@upstash/redis"
-const redis = Redis.fromEnv()
+import { Redis } from "@upstash/redis";
+const redis = Redis.fromEnv();
 ```
 
 ```ts
 // or when deploying to cloudflare workers
-import { Redis } from "@upstash/redis/cloudflare"
-const redis = Redis.fromEnv()
+import { Redis } from "@upstash/redis/cloudflare";
+const redis = Redis.fromEnv();
 ```
 
 ### Error handling
@@ -162,50 +173,56 @@ Errors are now thrown automatically instead of being returned to you.
 
 ```ts
 // old
-const { data, error } = await set("key", "value")
+const { data, error } = await set("key", "value");
 if (error) {
-  throw new Error(error)
+  throw new Error(error);
 }
 
 // new
-const data = await redis.set("key", "value") // error is thrown automatically
+const data = await redis.set("key", "value"); // error is thrown automatically
 ```
 
 ## Pipeline
 
-`v1.0.0` introduces redis pipelines.
-Pipelining commands allows you to send a single http request with multiple commands.
+`v1.0.0` introduces redis pipelines. Pipelining commands allows you to send a
+single http request with multiple commands.
 
 ```ts
-import { Redis } from "@upstash/redis"
+import { Redis } from "@upstash/redis";
 
 const redis = new Redis({
   /* auth */
-})
+});
 
-const p = redis.pipeline()
+const p = redis.pipeline();
 
 // Now you can chain multiple commands to create your pipeline:
 
-p.set("key", 2)
-p.incr("key")
+p.set("key", 2);
+p.incr("key");
 
 // or inline:
-p.hset("key2", "field", { hello: "world" }).hvals("key2")
+p.hset("key2", "field", { hello: "world" }).hvals("key2");
 
 // Execute the pipeline once you are done building it:
 // `exec` returns an array where each element represents the response of a command in the pipeline.
 // You can optionally provide a type like this to get a typed response.
-const res = await p.exec<[Type1, Type2, Type3]>()
+const res = await p.exec<[Type1, Type2, Type3]>();
 ```
 
-For more information about pipelines using REST see [here](https://blog.upstash.com/pipeline).
+For more information about pipelines using REST see
+[here](https://blog.upstash.com/pipeline).
 
 ### Advanced
 
-A low level `Command` class can be imported from `@upstash/redis` in case you need more control about types and or (de)serialization.
+A low level `Command` class can be imported from `@upstash/redis` in case you
+need more control about types and or (de)serialization.
 
-By default all objects you are storing in redis are serialized using `JSON.stringify` and recursively deserialized as well. Here's an example how you could customize that behaviour. Keep in mind that you need to provide a `fetch` polyfill if you are running on nodejs. We recommend [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch).
+By default all objects you are storing in redis are serialized using
+`JSON.stringify` and recursively deserialized as well. Here's an example how you
+could customize that behaviour. Keep in mind that you need to provide a `fetch`
+polyfill if you are running on nodejs. We recommend
+[isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch).
 
 ```ts
 import { Command } from "@upstash/redis/commands"
@@ -232,25 +249,53 @@ const client = new HttpClient({
 })
 
 const res = new CustomGetCommand("key").exec(client)
+```
 
+### Additional information
+
+#### `keepalive`
+
+`@upstash/redis` is capable of reusing connections where possible to minimize
+latency. Connections can be reused if the client is stored in memory and not
+initialized with every new function invocation. The easiest way to achieve this
+is by creating the client outside of your handler and adding an https agent:
+
+```ts
+// Nextjs api route
+import { Redis } from "@upstash/redis";
+import https from "https";
+
+const redis = Redis.fromEnv({
+  agent: new https.Agent({ keepAlive: true }),
+});
+
+export default async function (req, res) {
+  // use redis here
+}
 ```
 
+Whenever your hot lambda receives a new request the client is already
+initialized and the previously established connection to upstash is reused.
+
 #### Javascript MAX_SAFE_INTEGER
 
-Javascript can not handle numbers larger than `2^53 -1` safely and would return wrong results when trying to deserialize them.
-In these cases the default deserializer will return them as string instead. This might cause a mismatch with your custom types.
+Javascript can not handle numbers larger than `2^53 -1` safely and would return
+wrong results when trying to deserialize them. In these cases the default
+deserializer will return them as string instead. This might cause a mismatch
+with your custom types.
 
 ```ts
-await redis.set("key", "101600000000150081467")
-const res = await redis<number>("get")
+await redis.set("key", "101600000000150081467");
+const res = await redis<number>("get");
 ```
 
-In this example `res` will still be a string despite the type annotation.
-Please keep that in mind and adjust accordingly.
+In this example `res` will still be a string despite the type annotation. Please
+keep that in mind and adjust accordingly.
 
 ## Docs
 
-See [the documentation](https://docs.upstash.com/features/javascriptsdk) for details.
+See [the documentation](https://docs.upstash.com/features/javascriptsdk) for
+details.
 
 ## Contributing
 
@@ -262,7 +307,8 @@ pnpm install
 
 ### Database
 
-Create a new redis database on [upstash](https://console.upstash.com/) and copy the url and token to `.env` (See `.env.example` for reference)
+Create a new redis database on [upstash](https://console.upstash.com/) and copy
+the url and token to `.env` (See `.env.example` for reference)
 
 ### Running tests
 

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/pkg/commands/append.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/append
+ */
+export class AppendCommand extends Command {
+    constructor(key, value) {
+        super(["append", key, value]);
+    }
+}

package/esm/pkg/commands/bitcount.js

@@ -0,0 +1,16 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/bitcount
+ */
+export class BitCountCommand extends Command {
+    constructor(key, start, end) {
+        const command = ["bitcount", key];
+        if (typeof start === "number") {
+            command.push(start);
+        }
+        if (typeof end === "number") {
+            command.push(end);
+        }
+        super(command);
+    }
+}

package/esm/pkg/commands/bitop.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/bitop
+ */
+export class BitOpCommand extends Command {
+    constructor(op, destinationKey, sourceKey, ...sourceKeys) {
+        super(["bitop", op, destinationKey, sourceKey, ...sourceKeys]);
+    }
+}

package/esm/pkg/commands/bitpos.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/bitpos
+ */
+export class BitPosCommand extends Command {
+    constructor(key, start, end) {
+        super(["bitpos", key, start, end]);
+    }
+}

package/esm/pkg/commands/command.js

@@ -0,0 +1,46 @@
+import { UpstashError } from "../error.js";
+import { parseResponse } from "../util.js";
+/**
+ * Command offers default (de)serialization and the exec method to all commands.
+ *
+ * TData represents what the user will enter or receive,
+ * TResult is the raw data returned from upstash, which may need to be transformed or parsed.
+ */
+export class Command {
+    /**
+     * Create a new command instance.
+     *
+     * You can define a custom `deserialize` function. By default we try to deserialize as json.
+     */
+    constructor(command, opts) {
+        Object.defineProperty(this, "command", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "deserialize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.command = command.map((c) => typeof c === "string" ? c : JSON.stringify(c));
+        this.deserialize = opts?.deserialize ?? parseResponse;
+    }
+    /**
+     * Execute the command using a client.
+     */
+    async exec(client) {
+        const { result, error } = await client.request({
+            body: this.command,
+        });
+        if (error) {
+            throw new UpstashError(error);
+        }
+        if (typeof result === "undefined") {
+            throw new Error(`Request did not return a result`);
+        }
+        return this.deserialize(result);
+    }
+}

package/esm/pkg/commands/dbsize.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/dbsize
+ */
+export class DBSizeCommand extends Command {
+    constructor() {
+        super(["dbsize"]);
+    }
+}

package/esm/pkg/commands/decr.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/decr
+ */
+export class DecrCommand extends Command {
+    constructor(key) {
+        super(["decr", key]);
+    }
+}

package/esm/pkg/commands/decrby.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/decrby
+ */
+export class DecrByCommand extends Command {
+    constructor(key, decrement) {
+        super(["decrby", key, decrement]);
+    }
+}

package/esm/pkg/commands/del.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/del
+ */
+export class DelCommand extends Command {
+    constructor(...keys) {
+        super(["del", ...keys]);
+    }
+}

package/esm/pkg/commands/echo.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/echo
+ */
+export class EchoCommand extends Command {
+    constructor(message) {
+        super(["echo", message]);
+    }
+}

package/esm/pkg/commands/eval.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/eval
+ */
+export class EvalCommand extends Command {
+    constructor(script, keys, args) {
+        super(["eval", script, keys.length, ...keys, ...(args ?? [])]);
+    }
+}

package/esm/pkg/commands/evalsha.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/evalsha
+ */
+export class EvalshaCommand extends Command {
+    constructor(sha, keys, args) {
+        super(["evalsha", sha, keys.length, ...keys, ...(args ?? [])]);
+    }
+}

package/esm/pkg/commands/exists.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/exists
+ */
+export class ExistsCommand extends Command {
+    constructor(...keys) {
+        super(["exists", ...keys]);
+    }
+}

package/esm/pkg/commands/expire.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/expire
+ */
+export class ExpireCommand extends Command {
+    constructor(key, seconds) {
+        super(["expire", key, seconds]);
+    }
+}

package/esm/pkg/commands/expireat.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/expireat
+ */
+export class ExpireAtCommand extends Command {
+    constructor(key, unix) {
+        super(["expireat", key, unix]);
+    }
+}

package/esm/pkg/commands/flushall.js

@@ -0,0 +1,13 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/flushall
+ */
+export class FlushAllCommand extends Command {
+    constructor(opts) {
+        const command = ["flushall"];
+        if (opts?.async) {
+            command.push("async");
+        }
+        super(command);
+    }
+}

package/esm/pkg/commands/flushdb.js

@@ -0,0 +1,13 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/flushdb
+ */
+export class FlushDBCommand extends Command {
+    constructor(opts) {
+        const command = ["flushdb"];
+        if (opts?.async) {
+            command.push("async");
+        }
+        super(command);
+    }
+}

package/esm/pkg/commands/get.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/get
+ */
+export class GetCommand extends Command {
+    constructor(key) {
+        super(["get", key]);
+    }
+}

package/esm/pkg/commands/getbit.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/getbit
+ */
+export class GetBitCommand extends Command {
+    constructor(key, offset) {
+        super(["getbit", key, offset]);
+    }
+}

package/esm/pkg/commands/getrange.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/getrange
+ */
+export class GetRangeCommand extends Command {
+    constructor(key, start, end) {
+        super(["getrange", key, start, end]);
+    }
+}

package/esm/pkg/commands/getset.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/getset
+ */
+export class GetSetCommand extends Command {
+    constructor(key, value) {
+        super(["getset", key, value]);
+    }
+}

package/esm/pkg/commands/hdel.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hdel
+ */
+export class HDelCommand extends Command {
+    constructor(key, field) {
+        super(["hdel", key, field]);
+    }
+}

package/esm/pkg/commands/hexists.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hexists
+ */
+export class HExistsCommand extends Command {
+    constructor(key, field) {
+        super(["hexists", key, field]);
+    }
+}

package/esm/pkg/commands/hget.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hget
+ */
+export class HGetCommand extends Command {
+    constructor(key, field) {
+        super(["hget", key, field]);
+    }
+}

package/esm/pkg/commands/hgetall.js

@@ -0,0 +1,30 @@
+import { Command } from "./command.js";
+/**
+ * @param result De
+ * @returns
+ */
+function deserialize(result) {
+    if (result.length === 0) {
+        return null;
+    }
+    const obj = {};
+    while (result.length >= 2) {
+        const key = result.shift();
+        const value = result.shift();
+        try {
+            obj[key] = JSON.parse(value);
+        }
+        catch {
+            obj[key] = value;
+        }
+    }
+    return obj;
+}
+/**
+ * @see https://redis.io/commands/hgetall
+ */
+export class HGetAllCommand extends Command {
+    constructor(key) {
+        super(["hgetall", key], { deserialize: (result) => deserialize(result) });
+    }
+}

package/esm/pkg/commands/hincrby.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hincrby
+ */
+export class HIncrByCommand extends Command {
+    constructor(key, field, increment) {
+        super(["hincrby", key, field, increment]);
+    }
+}

package/esm/pkg/commands/hincrbyfloat.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hincrbyfloat
+ */
+export class HIncrByFloatCommand extends Command {
+    constructor(key, field, increment) {
+        super(["hincrbyfloat", key, field, increment]);
+    }
+}

package/esm/pkg/commands/hkeys.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hkeys
+ */
+export class HKeysCommand extends Command {
+    constructor(key) {
+        super(["hkeys", key]);
+    }
+}

package/esm/pkg/commands/hlen.js

@@ -0,0 +1,9 @@
+import { Command } from "./command.js";
+/**
+ * @see https://redis.io/commands/hlen
+ */
+export class HLenCommand extends Command {
+    constructor(key) {
+        super(["hlen", key]);
+    }
+}