@sebspark/promise-cache 3.6.0 → 3.7.0

package/dist/index.js

@@ -483,6 +483,45 @@ var InMemoryPersistor = class {
     }
     return "OK";
   }
+  /**
+   * Stores a key-value pair with an expiration time in seconds.
+   * If the key already exists, it will be overwritten.
+   *
+   * @param key - The storage key.
+   * @param seconds - Expiration time in seconds.
+   * @param value - The string value to store.
+   * @returns Resolves to `'OK'` on success.
+   */
+  async setEx(key, seconds2, value) {
+    this.store.set(key, value);
+    await this.expire(key, seconds2);
+    return "OK";
+  }
+  /**
+   * Stores a key-value pair with an expiration time in milliseconds.
+   * If the key already exists, it will be overwritten.
+   *
+   * @param key - The storage key.
+   * @param milliseconds - Expiration time in milliseconds.
+   * @param value - The string value to store.
+   * @returns Resolves to `'OK'` on success.
+   */
+  async pSetEx(key, milliseconds, value) {
+    return this.setEx(key, milliseconds / 1e3, value);
+  }
+  /**
+   * Stores a key-value pair **only if the key does not already exist**.
+   * If the key exists, the operation fails and returns `false`.
+   *
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @returns Resolves to `true` if the key was set, or `false` if the key already exists.
+   */
+  async setNX(key, value) {
+    if (this.store.has(key)) return false;
+    this.store.set(key, value);
+    return true;
+  }
   /**
    * Retrieves the value associated with a key.
    *
@@ -535,6 +574,283 @@ var InMemoryPersistor = class {
     const timeLeft = this.expiryTimestamps.get(key) - Date.now();
     return timeLeft > 0 ? Math.ceil(timeLeft / 1e3) : -2;
   }
+  /**
+   * Checks if one or more keys exist in the store.
+   *
+   * @param {string | string[]} keys - A single key or an array of keys to check.
+   * @returns {Promise<number>} Resolves to the number of keys that exist.
+   */
+  async exists(keys) {
+    const keyArray = Array.isArray(keys) ? keys : [keys];
+    return keyArray.reduce(
+      (count, key) => this.store.has(key) ? count + 1 : count,
+      0
+    );
+  }
+  /**
+   * Increments a numeric value stored at a key by 1.
+   * If the key does not exist, it is set to `1`.
+   *
+   * @param {string} key - The key to increment.
+   * @returns {Promise<number>} Resolves to the new value after increment.
+   */
+  async incr(key) {
+    const current = Number(this.store.get(key)) || 0;
+    const newValue = current + 1;
+    this.store.set(key, newValue.toString());
+    return newValue;
+  }
+  /**
+   * Increments a numeric value stored at a key by a specified amount.
+   * If the key does not exist, it is set to the increment value.
+   *
+   * @param {string} key - The key to increment.
+   * @param {number} increment - The amount to increase by.
+   * @returns {Promise<number>} Resolves to the new value after increment.
+   */
+  async incrBy(key, increment) {
+    const current = Number(this.store.get(key)) || 0;
+    const newValue = current + increment;
+    this.store.set(key, newValue.toString());
+    return newValue;
+  }
+  /**
+   * Decrements a numeric value stored at a key by 1.
+   * If the key does not exist, it is set to `-1`.
+   *
+   * @param {string} key - The key to decrement.
+   * @returns {Promise<number>} Resolves to the new value after decrement.
+   */
+  async decr(key) {
+    const current = Number(this.store.get(key)) || 0;
+    const newValue = current - 1;
+    this.store.set(key, newValue.toString());
+    return newValue;
+  }
+  /**
+   * Decrements a numeric value stored at a key by a specified amount.
+   * If the key does not exist, it is set to the negative decrement value.
+   *
+   * @param {string} key - The key to decrement.
+   * @param {number} decrement - The amount to decrease by.
+   * @returns {Promise<number>} Resolves to the new value after decrement.
+   */
+  async decrBy(key, decrement) {
+    const current = Number(this.store.get(key)) || 0;
+    const newValue = current - decrement;
+    this.store.set(key, newValue.toString());
+    return newValue;
+  }
+  /**
+   * Sets a field in a hash.
+   * If the field already exists, its value is updated.
+   *
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @param value - The value to store.
+   * @returns Resolves to `1` if a new field was added, `0` if an existing field was updated.
+   */
+  async hSet(key, field, value) {
+    const existingHash = JSON.parse(this.store.get(key) ?? "{}");
+    const isNewField = !Object.prototype.hasOwnProperty.call(
+      existingHash,
+      field
+    );
+    existingHash[field] = value;
+    this.store.set(key, JSON.stringify(existingHash));
+    return isNewField ? 1 : 0;
+  }
+  /**
+   * Retrieves a field from a hash.
+   *
+   * @param key - The hash key.
+   * @param field - The field name to retrieve.
+   * @returns Resolves to the field value, or `undefined` if the field does not exist.
+   */
+  async hGet(key, field) {
+    const hash = JSON.parse(this.store.get(key) ?? "{}");
+    return hash[field] ?? void 0;
+  }
+  /**
+   * Pushes elements to the left (head) of a list.
+   *
+   * @param key - The list key.
+   * @param values - One or more values to add.
+   * @returns Resolves to the length of the list after the operation.
+   */
+  async lPush(key, values) {
+    const list = JSON.parse(this.store.get(key) ?? "[]");
+    const newValues = Array.isArray(values) ? values : [values];
+    const updatedList = [...newValues.reverse(), ...list];
+    this.store.set(key, JSON.stringify(updatedList));
+    return updatedList.length;
+  }
+  /**
+   * Pushes elements to the right (tail) of a list.
+   *
+   * @param key - The list key.
+   * @param values - One or more values to add.
+   * @returns Resolves to the length of the list after the operation.
+   */
+  async rPush(key, values) {
+    const list = JSON.parse(this.store.get(key) ?? "[]");
+    const newValues = Array.isArray(values) ? values : [values];
+    const updatedList = [...list, ...newValues];
+    this.store.set(key, JSON.stringify(updatedList));
+    return updatedList.length;
+  }
+  /**
+   * Removes and returns the first element from a list.
+   *
+   * @param key - The list key.
+   * @returns Resolves to the removed element, or `null` if the list is empty.
+   */
+  async lPop(key) {
+    const list = JSON.parse(this.store.get(key) ?? "[]");
+    if (list.length === 0) return null;
+    const value = list.shift();
+    if (list.length > 0) {
+      this.store.set(key, JSON.stringify(list));
+    } else {
+      this.store.delete(key);
+    }
+    return value;
+  }
+  /**
+   * Removes and returns the last element from a list.
+   *
+   * @param key - The list key.
+   * @returns Resolves to the removed element, or `null` if the list is empty.
+   */
+  async rPop(key) {
+    const list = JSON.parse(this.store.get(key) ?? "[]");
+    if (list.length === 0) return null;
+    const value = list.pop();
+    if (list.length > 0) {
+      this.store.set(key, JSON.stringify(list));
+    } else {
+      this.store.delete(key);
+    }
+    return value;
+  }
+  /**
+   * Retrieves a range of elements from a list.
+   *
+   * @param key - The list key.
+   * @param start - The starting index.
+   * @param stop - The stopping index.
+   * @returns Resolves to an array containing the requested range.
+   */
+  async lRange(key, start, stop) {
+    const list = JSON.parse(this.store.get(key) ?? "[]");
+    const normalizedStop = stop === -1 ? list.length : stop + 1;
+    return list.slice(start, normalizedStop);
+  }
+  /**
+   * Adds elements to a set.
+   *
+   * @param key - The set key.
+   * @param values - One or more values to add.
+   * @returns Resolves to the number of new elements added.
+   */
+  async sAdd(key, values) {
+    const set = new Set(JSON.parse(this.store.get(key) ?? "[]"));
+    const newValues = Array.isArray(values) ? values : [values];
+    const initialSize = set.size;
+    for (const value of newValues) {
+      set.add(value);
+    }
+    this.store.set(key, JSON.stringify([...set]));
+    return set.size - initialSize;
+  }
+  /**
+   * Removes elements from a set.
+   *
+   * @param key - The set key.
+   * @param values - One or more values to remove.
+   * @returns Resolves to the number of elements removed.
+   */
+  async sRem(key, values) {
+    const set = new Set(JSON.parse(this.store.get(key) ?? "[]"));
+    const valuesToRemove = Array.isArray(values) ? values : [values];
+    const initialSize = set.size;
+    for (const value of valuesToRemove) {
+      set.delete(value);
+    }
+    this.store.set(key, JSON.stringify([...set]));
+    return initialSize - set.size;
+  }
+  /**
+   * Retrieves all elements from a set.
+   *
+   * @param key - The set key.
+   * @returns Resolves to an array of all set members.
+   */
+  async sMembers(key) {
+    return JSON.parse(this.store.get(key) ?? "[]");
+  }
+  /**
+   * Adds members to a sorted set with scores.
+   *
+   * @param key - The sorted set key.
+   * @param members - An array of objects containing `{ score, value }`.
+   * @returns Resolves to the number of new elements added.
+   */
+  async zAdd(key, members) {
+    const sortedSet = JSON.parse(
+      this.store.get(key) ?? "[]"
+    );
+    const initialSize = sortedSet.length;
+    for (const { score, value } of members) {
+      const existingIndex = sortedSet.findIndex(
+        (entry) => entry.value === value
+      );
+      if (existingIndex !== -1) {
+        sortedSet[existingIndex].score = score;
+      } else {
+        sortedSet.push({ score, value });
+      }
+    }
+    sortedSet.sort((a, b) => a.score - b.score);
+    this.store.set(key, JSON.stringify(sortedSet));
+    return sortedSet.length - initialSize;
+  }
+  /**
+   * Retrieves a range of elements from a sorted set.
+   *
+   * @param key - The sorted set key.
+   * @param start - The starting index.
+   * @param stop - The stopping index.
+   * @returns Resolves to an array of sorted set values in the range.
+   */
+  async zRange(key, start, stop) {
+    const sortedSet = JSON.parse(
+      this.store.get(key) ?? "[]"
+    );
+    const normalizedStop = stop === -1 ? sortedSet.length : stop + 1;
+    return sortedSet.slice(start, normalizedStop).map((entry) => entry.value);
+  }
+  /**
+   * Removes elements from a sorted set.
+   *
+   * @param key - The sorted set key.
+   * @param members - One or more values to remove.
+   * @returns Resolves to the number of elements removed.
+   */
+  async zRem(key, members) {
+    const sortedSet = JSON.parse(
+      this.store.get(key) ?? "[]"
+    );
+    const valuesToRemove = Array.isArray(members) ? members : [members];
+    const initialSize = sortedSet.length;
+    this.store.set(
+      key,
+      JSON.stringify(
+        sortedSet.filter((entry) => !valuesToRemove.includes(entry.value))
+      )
+    );
+    return initialSize - JSON.parse(this.store.get(key) ?? "[]").length;
+  }
   /**
    * Removes all keys from the store and clears all active expirations.
    *
@@ -549,6 +865,15 @@ var InMemoryPersistor = class {
     this.expiryTimestamps.clear();
     return "OK";
   }
+  /**
+   * Creates a new multi-command batch instance.
+   * Commands queued in this batch will be executed together when `exec()` is called.
+   *
+   * @returns A new `IPersistorMulti` instance for batching commands.
+   */
+  multi() {
+    return new InMemoryMulti(this);
+  }
   /**
    * Sets an expiration timeout for a key.
    * Cancels any existing expiration before setting a new one.
@@ -582,6 +907,329 @@ var InMemoryPersistor = class {
     }
   }
 };
+var InMemoryMulti = class {
+  persistor;
+  commands = /* @__PURE__ */ new Set();
+  constructor(persistor) {
+    this.persistor = persistor;
+  }
+  /**
+   * Queues a `SET` command to store a key-value pair with optional expiration settings.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @param options - Optional expiration settings.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  set(key, value, options) {
+    this.commands.add(() => this.persistor.set(key, value, options));
+    return this;
+  }
+  /**
+   * Queues a `SETEX` command to store a key-value pair with an expiration time in seconds.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key.
+   * @param seconds - Expiration time in seconds.
+   * @param value - The string value to store.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  setEx(key, seconds2, value) {
+    this.commands.add(() => this.persistor.setEx(key, seconds2, value));
+    return this;
+  }
+  /**
+   * Queues a `PSETEX` command to store a key-value pair with an expiration time in milliseconds.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key.
+   * @param milliseconds - Expiration time in milliseconds.
+   * @param value - The string value to store.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  pSetEx(key, milliseconds, value) {
+    this.commands.add(() => this.persistor.pSetEx(key, milliseconds, value));
+    return this;
+  }
+  /**
+   * Queues a `SETNX` command to store a key-value pair **only if the key does not already exist**.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  setNX(key, value) {
+    this.commands.add(() => this.persistor.setNX(key, value));
+    return this;
+  }
+  /**
+   * Queues a `GET` command to retrieve the value associated with a key.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key to retrieve.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  get(key) {
+    this.commands.add(() => this.persistor.get(key));
+    return this;
+  }
+  /**
+   * Queues a `DEL` command to delete a key from the store.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key to delete.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  del(key) {
+    this.commands.add(() => this.persistor.del(key));
+    return this;
+  }
+  /**
+   * Queues an `EXPIRE` command to set a time-to-live (TTL) in seconds for a key.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key.
+   * @param seconds - TTL in seconds.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  expire(key, seconds2) {
+    this.commands.add(() => this.persistor.expire(key, seconds2));
+    return this;
+  }
+  /**
+   * Queues a `TTL` command to get the remaining time-to-live (TTL) of a key in seconds.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The storage key to check.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  ttl(key) {
+    this.commands.add(() => this.persistor.ttl(key));
+    return this;
+  }
+  /**
+   * Queues an `exists` operation in the batch.
+   * @param key - The key(s) to check existence.
+   * @returns The multi instance for method chaining.
+   */
+  exists(key) {
+    this.commands.add(() => this.persistor.exists(key));
+    return this;
+  }
+  /**
+   * Queues an `incr` operation in the batch.
+   * @param key - The key to increment.
+   * @returns The multi instance for method chaining.
+   */
+  incr(key) {
+    this.commands.add(() => this.persistor.incr(key));
+    return this;
+  }
+  /**
+   * Queues an `incrBy` operation in the batch.
+   * @param key - The key to increment.
+   * @param increment - The amount to increment by.
+   * @returns The multi instance for method chaining.
+   */
+  incrBy(key, increment) {
+    this.commands.add(() => this.persistor.incrBy(key, increment));
+    return this;
+  }
+  /**
+   * Queues a `decr` operation in the batch.
+   * @param key - The key to decrement.
+   * @returns The multi instance for method chaining.
+   */
+  decr(key) {
+    this.commands.add(() => this.persistor.decr(key));
+    return this;
+  }
+  /**
+   * Queues a `decrBy` operation in the batch.
+   * @param key - The key to decrement.
+   * @param decrement - The amount to decrement by.
+   * @returns The multi instance for method chaining.
+   */
+  decrBy(key, decrement) {
+    this.commands.add(() => this.persistor.decrBy(key, decrement));
+    return this;
+  }
+  /**
+   * Queues a `flushAll` operation in the batch.
+   * @returns The multi instance for method chaining.
+   */
+  flushAll() {
+    this.commands.add(() => this.persistor.flushAll());
+    return this;
+  }
+  /**
+   * Queues an `hSet` command to store a field-value pair in a hash.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @param value - The value to store.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  hSet(key, field, value) {
+    this.commands.add(() => this.persistor.hSet(key, field, value));
+    return this;
+  }
+  /**
+   * Queues an `hGet` command to retrieve a field value from a hash.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The hash key.
+   * @param field - The field to retrieve.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  hGet(key, field) {
+    this.commands.add(() => this.persistor.hGet(key, field));
+    return this;
+  }
+  /**
+   * Queues an `lPush` command to add elements to the left (head) of a list.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The list key.
+   * @param values - The values to add.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  lPush(key, values) {
+    this.commands.add(() => this.persistor.lPush(key, values));
+    return this;
+  }
+  /**
+   * Queues an `rPush` command to add elements to the right (tail) of a list.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The list key.
+   * @param values - The values to add.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  rPush(key, values) {
+    this.commands.add(() => this.persistor.rPush(key, values));
+    return this;
+  }
+  /**
+   * Queues an `lPop` command to remove and return the first element of a list.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The list key.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  lPop(key) {
+    this.commands.add(() => this.persistor.lPop(key));
+    return this;
+  }
+  /**
+   * Queues an `rPop` command to remove and return the last element of a list.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The list key.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  rPop(key) {
+    this.commands.add(() => this.persistor.rPop(key));
+    return this;
+  }
+  /**
+   * Queues an `lRange` command to retrieve a range of elements from a list.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The list key.
+   * @param start - The start index.
+   * @param stop - The stop index (inclusive).
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  lRange(key, start, stop) {
+    this.commands.add(() => this.persistor.lRange(key, start, stop));
+    return this;
+  }
+  /**
+   * Queues an `sAdd` command to add elements to a set.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The set key.
+   * @param values - The values to add.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  sAdd(key, values) {
+    this.commands.add(() => this.persistor.sAdd(key, values));
+    return this;
+  }
+  /**
+   * Queues an `sRem` command to remove elements from a set.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The set key.
+   * @param values - The values to remove.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  sRem(key, values) {
+    this.commands.add(() => this.persistor.sRem(key, values));
+    return this;
+  }
+  /**
+   * Queues an `sMembers` command to retrieve all members of a set.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The set key.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  sMembers(key) {
+    this.commands.add(() => this.persistor.sMembers(key));
+    return this;
+  }
+  /**
+   * Queues a `zAdd` command to add elements to a sorted set with scores.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The sorted set key.
+   * @param members - An array of objects with `score` and `value`.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  zAdd(key, members) {
+    this.commands.add(() => this.persistor.zAdd(key, members));
+    return this;
+  }
+  /**
+   * Queues a `zRange` command to retrieve a range of elements from a sorted set.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The sorted set key.
+   * @param start - The start index.
+   * @param stop - The stop index (inclusive).
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  zRange(key, start, stop) {
+    this.commands.add(() => this.persistor.zRange(key, start, stop));
+    return this;
+  }
+  /**
+   * Queues a `zRem` command to remove elements from a sorted set.
+   * The command will be executed when `exec()` is called.
+   *
+   * @param key - The sorted set key.
+   * @param members - The members to remove.
+   * @returns The `IPersistorMulti` instance to allow method chaining.
+   */
+  zRem(key, members) {
+    this.commands.add(() => this.persistor.zRem(key, members));
+    return this;
+  }
+  /**
+   * Executes multiple commands in a batch operation.
+   * Each command is executed in sequence, and results are collected in an array.
+   *
+   * @returns Resolves to an array containing the results of each queued command.
+   */
+  async exec() {
+    return Promise.all([...this.commands].map((cmd) => cmd()));
+  }
+};
 
 // src/time.ts
 var time_exports = {};