encore.dev 1.54.2 → 1.56.0

package/dist/storage/cache/list.js

@@ -0,0 +1,376 @@
+import { getCurrentRequest } from "../../internal/reqtrack/mod.js";
+import { Keyspace } from "./keyspace.js";
+/**
+ * Base class for list keyspaces with all list operations.
+ * Subclasses provide typed serialization/deserialization.
+ * @internal
+ */
+class ListKeyspace extends Keyspace {
+    constructor(cluster, config) {
+        super(cluster, config);
+    }
+    /**
+     * Pushes one or more values at the head of the list stored at key.
+     * If the key does not already exist, it is first created as an empty list.
+     *
+     * If multiple values are given, they are inserted one after another,
+     * starting with the leftmost value. For instance,
+     * `pushLeft(key, "a", "b", "c")` will result in a list containing
+     * "c" as its first element, "b" as its second, and "a" as its third.
+     *
+     * @returns The length of the list after the operation.
+     * @see https://redis.io/commands/lpush/
+     */
+    async pushLeft(key, ...values) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const serialized = values.map((v) => this.serializeItem(v));
+        const ttlMs = this.resolveTtl();
+        const result = await this.cluster.impl.lpush(mappedKey, serialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Pushes one or more values at the tail of the list stored at key.
+     * If the key does not already exist, it is first created as an empty list.
+     *
+     * If multiple values are given, they are inserted one after another,
+     * starting with the leftmost value. For instance,
+     * `pushRight(key, "a", "b", "c")` will result in a list containing
+     * "a" as its first element, "b" as its second, and "c" as its third.
+     *
+     * @returns The length of the list after the operation.
+     * @see https://redis.io/commands/rpush/
+     */
+    async pushRight(key, ...values) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const serialized = values.map((v) => this.serializeItem(v));
+        const ttlMs = this.resolveTtl();
+        const result = await this.cluster.impl.rpush(mappedKey, serialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Pops a single element off the head of the list stored at key.
+     *
+     * @returns The popped value, or `undefined` if the key does not exist.
+     * @see https://redis.io/commands/lpop/
+     */
+    async popLeft(key, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.lpop(mappedKey, ttlMs, source);
+        if (result === null) {
+            return undefined;
+        }
+        return this.deserializeItem(result);
+    }
+    /**
+     * Pops a single element off the tail of the list stored at key.
+     *
+     * @returns The popped value, or `undefined` if the key does not exist.
+     * @see https://redis.io/commands/rpop/
+     */
+    async popRight(key, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.rpop(mappedKey, ttlMs, source);
+        if (result === null) {
+            return undefined;
+        }
+        return this.deserializeItem(result);
+    }
+    /**
+     * Returns the length of the list stored at key.
+     *
+     * Non-existing keys are considered as empty lists.
+     *
+     * @returns The list length.
+     * @see https://redis.io/commands/llen/
+     */
+    async len(key) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const result = await this.cluster.impl.llen(mappedKey, source);
+        return Number(result);
+    }
+    /**
+     * Trims the list stored at key to only contain the elements between the indices
+     * `start` and `stop` (inclusive). Both are zero-based indices.
+     *
+     * Negative indices can be used to indicate offsets from the end of the list,
+     * where -1 is the last element of the list, -2 the penultimate element, and so on.
+     *
+     * Out of range indices are valid and are treated as if they specify the start or end of the list,
+     * respectively. If `start` > `stop` the end result is an empty list.
+     *
+     * @param key - The cache key.
+     * @param start - Start index (inclusive).
+     * @param stop - Stop index (inclusive).
+     * @see https://redis.io/commands/ltrim/
+     */
+    async trim(key, start, stop, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const ttlMs = this.resolveTtl(options);
+        await this.cluster.impl.ltrim(mappedKey, start, stop, ttlMs, source);
+    }
+    /**
+     * Updates the list element at the given index.
+     *
+     * Negative indices can be used to indicate offsets from the end of the list,
+     * where -1 is the last element of the list, -2 the penultimate element, and so on.
+     *
+     * @param key - The cache key.
+     * @param index - Zero-based index of the element to update.
+     * @param value - The new value.
+     * @throws {Error} If the index is out of range.
+     * @see https://redis.io/commands/lset/
+     */
+    async set(key, index, value, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const serialized = this.serializeItem(value);
+        const ttlMs = this.resolveTtl(options);
+        await this.cluster.impl.lset(mappedKey, index, serialized, ttlMs, source);
+    }
+    /**
+     * Returns the value of the list element at the given index.
+     *
+     * Negative indices can be used to indicate offsets from the end of the list,
+     * where -1 is the last element of the list, -2 the penultimate element, and so on.
+     *
+     * @param key - The cache key.
+     * @param index - Zero-based index of the element to retrieve.
+     * @returns The value at the index, or `undefined` if out of range or the key does not exist.
+     * @see https://redis.io/commands/lindex/
+     */
+    async get(key, index) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const result = await this.cluster.impl.lindex(mappedKey, index, source);
+        if (result === null) {
+            return undefined;
+        }
+        return this.deserializeItem(result);
+    }
+    /**
+     * Returns all the elements in the list stored at key.
+     *
+     * If the key does not exist it returns an empty array.
+     *
+     * @returns All elements in the list.
+     * @see https://redis.io/commands/lrange/
+     */
+    async items(key) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const results = await this.cluster.impl.lrangeAll(mappedKey, source);
+        return results.map((r) => this.deserializeItem(r));
+    }
+    /**
+     * Returns the elements in the list stored at key between `start` and `stop` (inclusive).
+     * Both are zero-based indices.
+     *
+     * Negative indices can be used to indicate offsets from the end of the list,
+     * where -1 is the last element of the list, -2 the penultimate element, and so on.
+     *
+     * If the key does not exist it returns an empty array.
+     *
+     * @param key - The cache key.
+     * @param start - Start index (inclusive).
+     * @param stop - Stop index (inclusive).
+     * @returns The elements in the specified range.
+     * @see https://redis.io/commands/lrange/
+     */
+    async getRange(key, start, stop) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const results = await this.cluster.impl.lrange(mappedKey, start, stop, source);
+        return results.map((r) => this.deserializeItem(r));
+    }
+    /**
+     * Inserts `value` into the list stored at key, at the position just before `pivot`.
+     *
+     * If the list does not contain `pivot`, the value is not inserted and -1 is returned.
+     *
+     * @param key - The cache key.
+     * @param pivot - The existing element to insert before.
+     * @param value - The value to insert.
+     * @returns The new list length, or -1 if `pivot` was not found.
+     * @see https://redis.io/commands/linsert/
+     */
+    async insertBefore(key, pivot, value, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const pivotSerialized = this.serializeItem(pivot);
+        const valueSerialized = this.serializeItem(value);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.linsertBefore(mappedKey, pivotSerialized, valueSerialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Inserts `value` into the list stored at key, at the position just after `pivot`.
+     *
+     * If the list does not contain `pivot`, the value is not inserted and -1 is returned.
+     *
+     * @param key - The cache key.
+     * @param pivot - The existing element to insert after.
+     * @param value - The value to insert.
+     * @returns The new list length, or -1 if `pivot` was not found.
+     * @see https://redis.io/commands/linsert/
+     */
+    async insertAfter(key, pivot, value, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const pivotSerialized = this.serializeItem(pivot);
+        const valueSerialized = this.serializeItem(value);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.linsertAfter(mappedKey, pivotSerialized, valueSerialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Removes all occurrences of `value` in the list stored at key.
+     *
+     * If the list does not contain `value`, or the list does not exist, returns 0.
+     *
+     * @param key - The cache key.
+     * @param value - The value to remove.
+     * @returns The number of elements removed.
+     * @see https://redis.io/commands/lrem/
+     */
+    async removeAll(key, value, options) {
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const valueSerialized = this.serializeItem(value);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.lremAll(mappedKey, valueSerialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Removes the first `count` occurrences of `value` in the list stored at key,
+     * scanning from head to tail.
+     *
+     * If the list does not contain `value`, or the list does not exist, returns 0.
+     *
+     * @param key - The cache key.
+     * @param count - Maximum number of occurrences to remove.
+     * @param value - The value to remove.
+     * @returns The number of elements removed.
+     * @see https://redis.io/commands/lrem/
+     */
+    async removeFirst(key, count, value, options) {
+        if (count < 0) {
+            throw new Error("count must be non-negative");
+        }
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const valueSerialized = this.serializeItem(value);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.lremFirst(mappedKey, count, valueSerialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Removes the last `count` occurrences of `value` in the list stored at key,
+     * scanning from tail to head.
+     *
+     * If the list does not contain `value`, or the list does not exist, returns 0.
+     *
+     * @param key - The cache key.
+     * @param count - Maximum number of occurrences to remove.
+     * @param value - The value to remove.
+     * @returns The number of elements removed.
+     * @see https://redis.io/commands/lrem/
+     */
+    async removeLast(key, count, value, options) {
+        if (count < 0) {
+            throw new Error("count must be non-negative");
+        }
+        const source = getCurrentRequest();
+        const mappedKey = this.mapKey(key);
+        const valueSerialized = this.serializeItem(value);
+        const ttlMs = this.resolveTtl(options);
+        // Negative count means remove from tail to head
+        const result = await this.cluster.impl.lremLast(mappedKey, count, valueSerialized, ttlMs, source);
+        return Number(result);
+    }
+    /**
+     * Atomically moves an element from the list stored at `src` to the list stored at `dst`.
+     *
+     * The value moved can be either the head (`srcPos === "left"`) or tail (`srcPos === "right"`)
+     * of the list at `src`. Similarly, the value can be placed either at the head (`dstPos === "left"`)
+     * or tail (`dstPos === "right"`) of the list at `dst`.
+     *
+     * If `src` and `dst` are the same list, the value is atomically rotated from one end to the other
+     * when `srcPos !== dstPos`, or if `srcPos === dstPos` nothing happens.
+     *
+     * @param src - Source list key.
+     * @param dst - Destination list key.
+     * @param srcPos - Position to pop from in the source list.
+     * @param dstPos - Position to push to in the destination list.
+     * @returns The moved element, or `undefined` if the source list does not exist.
+     * @see https://redis.io/commands/lmove/
+     */
+    async move(src, dst, srcPos, dstPos, options) {
+        const source = getCurrentRequest();
+        const srcKey = this.mapKey(src);
+        const dstKey = this.mapKey(dst);
+        const ttlMs = this.resolveTtl(options);
+        const result = await this.cluster.impl.lmove(srcKey, dstKey, srcPos, dstPos, ttlMs, source);
+        if (result === null || result === undefined) {
+            return undefined;
+        }
+        return this.deserializeItem(result);
+    }
+}
+/**
+ * StringListKeyspace stores lists of string values.
+ *
+ * @example
+ * ```ts
+ * const recentViews = new StringListKeyspace<string>(cluster, {
+ *   keyPattern: "recent-views/:userId",
+ *   defaultExpiry: ExpireIn(86400000), // 24 hours
+ * });
+ *
+ * await recentViews.pushLeft("user1", "product-123", "product-456");
+ * const views = await recentViews.items("user1");
+ * ```
+ */
+export class StringListKeyspace extends ListKeyspace {
+    constructor(cluster, config) {
+        super(cluster, config);
+    }
+    serializeItem(value) {
+        return Buffer.from(value, "utf-8");
+    }
+    deserializeItem(data) {
+        return data.toString("utf-8");
+    }
+}
+/**
+ * NumberListKeyspace stores lists of numeric values.
+ *
+ * @example
+ * ```ts
+ * const scores = new NumberListKeyspace<string>(cluster, {
+ *   keyPattern: "scores/:gameId",
+ * });
+ *
+ * await scores.pushRight("game1", 100, 200, 300);
+ * const allScores = await scores.items("game1");
+ * ```
+ */
+export class NumberListKeyspace extends ListKeyspace {
+    constructor(cluster, config) {
+        super(cluster, config);
+    }
+    serializeItem(value) {
+        return Buffer.from(String(value), "utf-8");
+    }
+    deserializeItem(data) {
+        return Number(data.toString("utf-8"));
+    }
+}
+//# sourceMappingURL=list.js.map

package/dist/storage/cache/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../storage/cache/list.ts"],"names":[],"mappings":"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"}

package/dist/storage/cache/mod.d.ts

@@ -0,0 +1,10 @@
+export { CacheCluster } from "./cluster.js";
+export type { CacheClusterConfig, EvictionPolicy } from "./cluster.js";
+export type { KeyspaceConfig, WriteOptions } from "./keyspace.js";
+export { StringKeyspace, IntKeyspace, FloatKeyspace, StructKeyspace } from "./basic.js";
+export { StringListKeyspace, NumberListKeyspace } from "./list.js";
+export type { ListPosition } from "./list.js";
+export { StringSetKeyspace, NumberSetKeyspace } from "./set.js";
+export { expireIn, expireInSeconds, expireInMinutes, expireInHours, expireDailyAt, neverExpire, keepTTL } from "./expiry.js";
+export type { Expiry } from "./expiry.js";
+export { CacheError, CacheMiss, CacheKeyExists } from "./errors.js";

package/dist/storage/cache/mod.js

@@ -0,0 +1,13 @@
+// Cache cluster
+export { CacheCluster } from "./cluster.js";
+// Basic keyspaces
+export { StringKeyspace, IntKeyspace, FloatKeyspace, StructKeyspace } from "./basic.js";
+// List keyspaces
+export { StringListKeyspace, NumberListKeyspace } from "./list.js";
+// Set keyspaces
+export { StringSetKeyspace, NumberSetKeyspace } from "./set.js";
+// Expiry utilities
+export { expireIn, expireInSeconds, expireInMinutes, expireInHours, expireDailyAt, neverExpire, keepTTL } from "./expiry.js";
+// Error types
+export { CacheError, CacheMiss, CacheKeyExists } from "./errors.js";
+//# sourceMappingURL=mod.js.map

package/dist/storage/cache/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../storage/cache/mod.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAMzC,kBAAkB;AAClB,OAAO,EACL,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB,iBAAiB;AACjB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAGhE,gBAAgB;AAChB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE7D,mBAAmB;AACnB,OAAO,EACL,QAAQ,EACR,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,WAAW,EACX,OAAO,EACR,MAAM,UAAU,CAAC;AAGlB,cAAc;AACd,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/storage/cache/set.d.ts

@@ -0,0 +1,258 @@
+/// <reference types="node" />
+import { CacheCluster } from "./cluster.js";
+import { Keyspace, KeyspaceConfig, WriteOptions } from "./keyspace.js";
+/**
+ * Base class for set keyspaces with all set operations.
+ * Subclasses provide typed serialization/deserialization.
+ * @internal
+ */
+declare abstract class SetKeyspace<K, V> extends Keyspace<K> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected abstract serializeItem(value: V): Buffer;
+    protected abstract deserializeItem(data: Buffer): V;
+    /**
+     * Adds one or more values to the set stored at key.
+     * If the key does not already exist, it is first created as an empty set.
+     *
+     * @returns The number of values that were added to the set,
+     * not including values already present beforehand.
+     * @see https://redis.io/commands/sadd/
+     */
+    add(key: K, ...members: V[]): Promise<number>;
+    /**
+     * Removes one or more values from the set stored at key.
+     * Values not present in the set are ignored.
+     * If the key does not already exist, it is a no-op.
+     *
+     * @returns The number of values that were removed from the set.
+     * @see https://redis.io/commands/srem/
+     */
+    remove(key: K, ...members: V[]): Promise<number>;
+    /**
+     * Removes a random element from the set stored at key and returns it.
+     *
+     * @returns The removed member, or `undefined` if the set is empty.
+     * @see https://redis.io/commands/spop/
+     */
+    popOne(key: K, options?: WriteOptions): Promise<V | undefined>;
+    /**
+     * Removes up to `count` random elements (bounded by the set's size)
+     * from the set stored at key and returns them.
+     *
+     * If the set is empty it returns an empty array.
+     *
+     * @param key - The cache key.
+     * @param count - Number of members to pop.
+     * @returns The removed members (may be fewer than `count` if the set is small).
+     * @see https://redis.io/commands/spop/
+     */
+    pop(key: K, count: number, options?: WriteOptions): Promise<V[]>;
+    /**
+     * Reports whether the set stored at key contains the given value.
+     *
+     * If the key does not exist it returns `false`.
+     *
+     * @returns `true` if the member exists in the set, `false` otherwise.
+     * @see https://redis.io/commands/sismember/
+     */
+    contains(key: K, member: V): Promise<boolean>;
+    /**
+     * Returns the number of elements in the set stored at key.
+     *
+     * If the key does not exist it returns 0.
+     *
+     * @returns The set cardinality.
+     * @see https://redis.io/commands/scard/
+     */
+    len(key: K): Promise<number>;
+    /**
+     * Returns the elements in the set stored at key.
+     *
+     * If the key does not exist it returns an empty array.
+     *
+     * @returns All members of the set.
+     * @see https://redis.io/commands/smembers/
+     */
+    items(key: K): Promise<V[]>;
+    /**
+     * Identical to {@link items} except it returns the values as a `Set`.
+     *
+     * If the key does not exist it returns an empty `Set`.
+     *
+     * @returns All members of the set as a `Set`.
+     * @see https://redis.io/commands/smembers/
+     */
+    itemsSet(key: K): Promise<Set<V>>;
+    /**
+     * Computes the set difference between the first set and all the consecutive sets.
+     *
+     * Set difference means the values present in the first set that are not present
+     * in any of the other sets.
+     *
+     * Keys that do not exist are considered as empty sets.
+     *
+     * @param keys - Keys of sets to compute difference for. At least one must be provided.
+     * @returns Members in the first set but not in any of the other sets.
+     * @throws {Error} If no keys are provided.
+     * @see https://redis.io/commands/sdiff/
+     */
+    diff(...keys: K[]): Promise<V[]>;
+    /**
+     * Identical to {@link diff} except it returns the values as a `Set`.
+     *
+     * @see https://redis.io/commands/sdiff/
+     */
+    diffSet(...keys: K[]): Promise<Set<V>>;
+    /**
+     * Computes the set difference between keys (like {@link diff}) and stores the result
+     * in `destination`.
+     *
+     * @param destination - Key to store the result.
+     * @param keys - Keys of sets to compute difference for.
+     * @returns The size of the resulting set.
+     * @see https://redis.io/commands/sdiffstore/
+     */
+    diffStore(destination: K, ...keys: K[]): Promise<number>;
+    /**
+     * Computes the set intersection between the sets stored at the given keys.
+     *
+     * Set intersection means the values common to all the provided sets.
+     *
+     * Keys that do not exist are considered to be empty sets.
+     * As a result, if any key is missing the final result is the empty set.
+     *
+     * @param keys - Keys of sets to compute intersection for. At least one must be provided.
+     * @returns Members common to all sets.
+     * @throws {Error} If no keys are provided.
+     * @see https://redis.io/commands/sinter/
+     */
+    intersect(...keys: K[]): Promise<V[]>;
+    /**
+     * Identical to {@link intersect} except it returns the values as a `Set`.
+     *
+     * @see https://redis.io/commands/sinter/
+     */
+    intersectSet(...keys: K[]): Promise<Set<V>>;
+    /**
+     * Computes the set intersection between keys (like {@link intersect}) and stores the result
+     * in `destination`.
+     *
+     * @param destination - Key to store the result.
+     * @param keys - Keys of sets to compute intersection for.
+     * @returns The size of the resulting set.
+     * @see https://redis.io/commands/sinterstore/
+     */
+    intersectStore(destination: K, ...keys: K[]): Promise<number>;
+    /**
+     * Computes the set union between the sets stored at the given keys.
+     *
+     * Set union means the values present in at least one of the provided sets.
+     *
+     * Keys that do not exist are considered to be empty sets.
+     *
+     * @param keys - Keys of sets to compute union for. At least one must be provided.
+     * @returns Members in any of the provided sets.
+     * @throws {Error} If no keys are provided.
+     * @see https://redis.io/commands/sunion/
+     */
+    union(...keys: K[]): Promise<V[]>;
+    /**
+     * Identical to {@link union} except it returns the values as a `Set`.
+     *
+     * @see https://redis.io/commands/sunion/
+     */
+    unionSet(...keys: K[]): Promise<Set<V>>;
+    /**
+     * Computes the set union between sets (like {@link union}) and stores the result
+     * in `destination`.
+     *
+     * @param destination - Key to store the result.
+     * @param keys - Keys of sets to compute union for.
+     * @returns The size of the resulting set.
+     * @see https://redis.io/commands/sunionstore/
+     */
+    unionStore(destination: K, ...keys: K[]): Promise<number>;
+    /**
+     * Returns a random member from the set stored at key without removing it.
+     *
+     * @returns A random member, or `undefined` if the key does not exist.
+     * @see https://redis.io/commands/srandmember/
+     */
+    sampleOne(key: K): Promise<V | undefined>;
+    /**
+     * Returns up to `count` distinct random elements from the set stored at key.
+     * The same element is never returned multiple times.
+     *
+     * If the key does not exist it returns an empty array.
+     *
+     * @param key - The cache key.
+     * @param count - Number of distinct members to return.
+     * @returns Random members (may be fewer than `count` if the set is small).
+     * @see https://redis.io/commands/srandmember/
+     */
+    sample(key: K, count: number): Promise<V[]>;
+    /**
+     * Returns `count` random elements from the set stored at key.
+     * The same element may be returned multiple times.
+     *
+     * If the key does not exist it returns an empty array.
+     *
+     * @param key - The cache key.
+     * @param count - Number of members to return (may include duplicates).
+     * @returns Random members, possibly with duplicates.
+     * @see https://redis.io/commands/srandmember/
+     */
+    sampleWithReplacement(key: K, count: number): Promise<V[]>;
+    /**
+     * Atomically moves the given member from the set stored at `src`
+     * to the set stored at `dst`.
+     *
+     * If the element already exists in `dst` it is still removed from `src`.
+     *
+     * @param src - Source set key.
+     * @param dst - Destination set key.
+     * @param member - The member to move.
+     * @returns `true` if the member was moved, `false` if not found in `src`.
+     * @see https://redis.io/commands/smove/
+     */
+    move(src: K, dst: K, member: V, options?: WriteOptions): Promise<boolean>;
+}
+/**
+ * StringSetKeyspace stores sets of unique string values.
+ *
+ * @example
+ * ```ts
+ * const tags = new StringSetKeyspace<string>(cluster, {
+ *   keyPattern: "tags/:articleId",
+ * });
+ *
+ * await tags.add("article1", "typescript", "programming", "web");
+ * const hasTech = await tags.contains("article1", "typescript");
+ * const allTags = await tags.items("article1");
+ * const tagSet = await tags.itemsSet("article1");
+ * ```
+ */
+export declare class StringSetKeyspace<K> extends SetKeyspace<K, string> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected serializeItem(value: string): Buffer;
+    protected deserializeItem(data: Buffer): string;
+}
+/**
+ * NumberSetKeyspace stores sets of unique numeric values.
+ *
+ * @example
+ * ```ts
+ * const scores = new NumberSetKeyspace<string>(cluster, {
+ *   keyPattern: "unique-scores/:gameId",
+ * });
+ *
+ * await scores.add("game1", 100, 200, 300);
+ * const hasScore = await scores.contains("game1", 100);
+ * ```
+ */
+export declare class NumberSetKeyspace<K> extends SetKeyspace<K, number> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected serializeItem(value: number): Buffer;
+    protected deserializeItem(data: Buffer): number;
+}
+export {};