encore.dev 1.54.2 → 1.56.0

package/storage/cache/cluster.ts

@@ -0,0 +1,67 @@
+import * as runtime from "../../internal/runtime/mod";
+import { StringLiteral } from "../../internal/utils/constraints";
+
+/**
+ * Redis eviction policy that determines how keys are evicted when memory is full.
+ */
+export type EvictionPolicy =
+  | "noeviction"
+  | "allkeys-lru"
+  | "allkeys-lfu"
+  | "allkeys-random"
+  | "volatile-lru"
+  | "volatile-lfu"
+  | "volatile-ttl"
+  | "volatile-random";
+
+/**
+ * Configuration options for a cache cluster.
+ */
+export interface CacheClusterConfig {
+  /**
+   * The eviction policy to use when the cache is full.
+   * Defaults to "allkeys-lru".
+   */
+  evictionPolicy?: EvictionPolicy;
+}
+
+/**
+ * CacheCluster represents a Redis cache cluster.
+ *
+ * Create a new cluster using `new CacheCluster(name)`.
+ * Reference an existing cluster using `CacheCluster.named(name)`.
+ *
+ * @example
+ * ```ts
+ * import { CacheCluster } from "encore.dev/storage/cache";
+ *
+ * const myCache = new CacheCluster("my-cache", {
+ *   evictionPolicy: "allkeys-lru",
+ * });
+ * ```
+ */
+export class CacheCluster {
+  /** @internal */
+  readonly impl: runtime.CacheCluster;
+  /** @internal */
+  readonly clusterName: string;
+
+  /**
+   * Creates a new cache cluster with the given name and configuration.
+   * @param name - The unique name for this cache cluster
+   * @param cfg - Optional configuration for the cluster
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(name: string, cfg?: CacheClusterConfig) {
+    this.clusterName = name;
+    this.impl = runtime.RT.cacheCluster(name);
+  }
+
+  /**
+   * Reference an existing cache cluster by name.
+   * To create a new cache cluster, use `new CacheCluster(...)` instead.
+   */
+  static named<Name extends string>(name: StringLiteral<Name>): CacheCluster {
+    return new CacheCluster(name);
+  }
+}

package/storage/cache/errors.ts

@@ -0,0 +1,66 @@
+/**
+ * CacheError is the base class for all cache-related errors.
+ */
+export class CacheError extends Error {
+  constructor(msg: string) {
+    // extending errors causes issues after you construct them, unless you apply the following fixes
+    super(msg);
+
+    // set error name as constructor name, make it not enumerable to keep native Error behavior
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new.target#new.target_in_constructors
+    Object.defineProperty(this, "name", {
+      value: "CacheError",
+      enumerable: false,
+      configurable: true
+    });
+
+    // Fix the prototype chain, capture stack trace.
+    Object.setPrototypeOf(this, CacheError.prototype);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * CacheMiss is thrown when a cache key is not found.
+ */
+export class CacheMiss extends CacheError {
+  constructor(key: string) {
+    // extending errors causes issues after you construct them, unless you apply the following fixes
+    super(`cache key "${key}" not found`);
+
+    // set error name as constructor name, make it not enumerable to keep native Error behavior
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new.target#new.target_in_constructors
+    Object.defineProperty(this, "name", {
+      value: "CacheMiss",
+      enumerable: false,
+      configurable: true
+    });
+
+    // Fix the prototype chain, capture stack trace.
+    Object.setPrototypeOf(this, CacheMiss.prototype);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * CacheKeyExists is thrown when attempting to set a key that already exists
+ * using setIfNotExists.
+ */
+export class CacheKeyExists extends CacheError {
+  constructor(key: string) {
+    // extending errors causes issues after you construct them, unless you apply the following fixes
+    super(`cache key "${key}" already exists`);
+
+    // set error name as constructor name, make it not enumerable to keep native Error behavior
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new.target#new.target_in_constructors
+    Object.defineProperty(this, "name", {
+      value: "CacheKeyExists",
+      enumerable: false,
+      configurable: true
+    });
+
+    // Fix the prototype chain, capture stack trace.
+    Object.setPrototypeOf(this, CacheKeyExists.prototype);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/storage/cache/expiry.ts

@@ -0,0 +1,98 @@
+/**
+ * Expiry represents a cache key expiration configuration.
+ * Use the helper functions to create expiry configurations.
+ */
+export type Expiry =
+  | { type: "duration"; durationMs: number }
+  | { type: "time"; hours: number; minutes: number; seconds: number }
+  | "never"
+  | "keep-ttl";
+
+/**
+ * expireIn sets the cache entry to expire after the specified duration.
+ * @param ms - Duration in milliseconds
+ */
+export function expireIn(ms: number): Expiry {
+  return { type: "duration", durationMs: ms };
+}
+
+/**
+ * expireInSeconds sets the cache entry to expire after the specified seconds.
+ * @param seconds - Duration in seconds
+ */
+export function expireInSeconds(seconds: number): Expiry {
+  return { type: "duration", durationMs: seconds * 1000 };
+}
+
+/**
+ * expireInMinutes sets the cache entry to expire after the specified minutes.
+ * @param minutes - Duration in minutes
+ */
+export function expireInMinutes(minutes: number): Expiry {
+  return { type: "duration", durationMs: minutes * 60 * 1000 };
+}
+
+/**
+ * expireInHours sets the cache entry to expire after the specified hours.
+ * @param hours - Duration in hours
+ */
+export function expireInHours(hours: number): Expiry {
+  return { type: "duration", durationMs: hours * 60 * 60 * 1000 };
+}
+
+/**
+ * expireDailyAt sets the cache entry to expire at a specific time each day (UTC).
+ * @param hours - Hour (0-23)
+ * @param minutes - Minutes (0-59)
+ * @param seconds - Seconds (0-59)
+ */
+export function expireDailyAt(
+  hours: number,
+  minutes: number,
+  seconds: number
+): Expiry {
+  return { type: "time", hours, minutes, seconds };
+}
+
+/**
+ * neverExpire sets the cache entry to never expire.
+ * Note: Redis may still evict the key based on the eviction policy.
+ */
+export const neverExpire: Expiry = "never";
+
+/**
+ * keepTTL preserves the existing TTL when updating a cache entry.
+ * If the key doesn't exist, no TTL is set.
+ */
+export const keepTTL: Expiry = "keep-ttl";
+
+/**
+ * Resolves an Expiry to a duration in milliseconds, "never", or "keep-ttl".
+ * @internal
+ */
+export function resolveExpiry(expiry: Expiry): number | "never" | "keep-ttl" {
+  switch (expiry) {
+    case "never":
+      return "never";
+    case "keep-ttl":
+      return "keep-ttl";
+  }
+
+  switch (expiry.type) {
+    case "duration":
+      return expiry.durationMs;
+
+    case "time": {
+      const now = new Date();
+      const target = new Date(now);
+      target.setUTCHours(expiry.hours, expiry.minutes, expiry.seconds, 0);
+
+      // If target time has passed today, set for tomorrow
+      if (target.getTime() <= now.getTime()) {
+        target.setUTCDate(target.getUTCDate() + 1);
+      }
+
+      return target.getTime() - now.getTime();
+    }
+  }
+}

package/storage/cache/keyspace.ts

@@ -0,0 +1,142 @@
+import { getCurrentRequest } from "../../internal/reqtrack/mod";
+import { CacheCluster } from "./cluster";
+import { Expiry, keepTTL, neverExpire, resolveExpiry } from "./expiry";
+
+/**
+ * Configuration for a cache keyspace.
+ */
+export interface KeyspaceConfig<K> {
+  /**
+   * The pattern for generating cache keys.
+   * Use `:fieldName` to include a field from the key type.
+   *
+   * @example
+   * // For a simple key type (string, number)
+   * keyPattern: "user/:id"
+   *
+   * // For a struct key type
+   * keyPattern: "user/:userId/region/:region"
+   */
+  keyPattern: string;
+
+  /**
+   * Default expiry for cache entries in this keyspace.
+   * If not set, entries do not expire.
+   */
+  defaultExpiry?: Expiry;
+}
+
+/**
+ * Options for write operations.
+ */
+export interface WriteOptions {
+  /**
+   * Expiry for this specific write operation.
+   * Overrides the keyspace's defaultExpiry.
+   */
+  expiry?: Expiry;
+}
+
+/**
+ * Base class for all keyspace types (basic, list, set).
+ * Provides key mapping, TTL resolution, with(), and delete().
+ * @internal
+ */
+export abstract class Keyspace<K> {
+  protected readonly cluster: CacheCluster;
+  protected readonly config: KeyspaceConfig<K>;
+  protected readonly keyMapper: (key: K) => string;
+  private _effectiveExpiry?: Expiry;
+
+  constructor(cluster: CacheCluster, config: KeyspaceConfig<K>) {
+    this.cluster = cluster;
+    this.config = config;
+    this.keyMapper = this.createKeyMapper(config.keyPattern);
+  }
+
+  /**
+   * Creates a key mapper by parsing the key pattern.
+   */
+  private createKeyMapper(pattern: string): (key: K) => string {
+    const segments = pattern.split("/").map((seg) => {
+      if (seg.startsWith(":")) {
+        return { isLiteral: false, value: seg.slice(1), field: seg.slice(1) };
+      }
+      return { isLiteral: true, value: seg };
+    });
+
+    return (key: K) => {
+      return segments
+        .map((seg) => {
+          if (seg.isLiteral) return seg.value;
+
+          let val: unknown;
+          if (typeof key === "object" && key !== null && seg.field) {
+            val = (key as Record<string, unknown>)[seg.field];
+          } else {
+            val = key;
+          }
+
+          // Escape forward slashes in string values
+          const str = String(val);
+          return str.replace(/\//g, "\\/");
+        })
+        .join("/");
+    };
+  }
+
+  /**
+   * Maps a key to its Redis key string.
+   */
+  protected mapKey(key: K): string {
+    const mapped = this.keyMapper(key);
+    if (mapped.startsWith("__encore")) {
+      throw new Error('use of reserved key prefix "__encore"');
+    }
+    return mapped;
+  }
+
+  /**
+   * Resolves the TTL for a write operation.
+   * Returns i64 sentinel for NAPI: undefined=no config, -1=KeepTTL, -2=Persist/NeverExpire, >=0=ms
+   */
+  protected resolveTtl(options?: WriteOptions): number | undefined {
+    const expiry =
+      options?.expiry ?? this._effectiveExpiry ?? this.config.defaultExpiry;
+    if (!expiry) return undefined;
+
+    const resolved = resolveExpiry(expiry);
+    if (resolved === "keep-ttl") return -1; // KeepTTL
+    if (resolved === "never") return -2; // NeverExpire → Persist
+    return resolved; // milliseconds
+  }
+
+  /**
+   * Returns a shallow clone of this keyspace with the specified write options applied.
+   * This allows setting expiry for a chain of operations.
+   *
+   * @example
+   * ```ts
+   * await myKeyspace.with({ expiry: expireIn(5000) }).set(key, value);
+   * ```
+   */
+  with(options: WriteOptions): this {
+    const clone = Object.create(Object.getPrototypeOf(this)) as this;
+    Object.assign(clone, this);
+    (clone as any)._effectiveExpiry = options.expiry ?? this._effectiveExpiry;
+    return clone;
+  }
+
+  /**
+   * Deletes the specified keys.
+   * If a key does not exist it is ignored.
+   *
+   * @returns The number of keys that were deleted.
+   * @see https://redis.io/commands/del/
+   */
+  async delete(...keys: K[]): Promise<number> {
+    const source = getCurrentRequest();
+    const mappedKeys = keys.map((k) => this.mapKey(k));
+    return await this.cluster.impl.delete(mappedKeys, source);
+  }
+}