encore.dev 1.54.2 → 1.55.0

package/config/secrets.ts

@@ -48,13 +48,19 @@ export type AnySecret = Secret<string>;
  *  const foo = secret<"foo">();
  */
 export function secret<Name extends string>(
-  name: StringLiteral<Name>,
+  name: StringLiteral<Name>
 ): Secret<Name> {
   // Get the secret implementation from the runtime.
   // It reports null if the secret isn't in the runtime config.
   const impl = runtime.RT.secret(name);
   const secretObj = () => {
     if (impl === null) {
+      // During local development we don't consider missing secrets a fatal error.
+      if (
+        runtime.RT.appMeta().environment.cloud === runtime.CloudProvider.Local
+      ) {
+        return "";
+      }
       throw new Error(`secret ${name} is not set`);
     }
     return impl.cached();

package/dist/config/secrets.js

@@ -14,6 +14,10 @@ export function secret(name) {
     const impl = runtime.RT.secret(name);
     const secretObj = () => {
         if (impl === null) {
+            // During local development we don't consider missing secrets a fatal error.
+            if (runtime.RT.appMeta().environment.cloud === runtime.CloudProvider.Local) {
+                return "";
+            }
             throw new Error(`secret ${name} is not set`);
         }
         return impl.cached();

package/dist/config/secrets.js.map

@@ -1 +1 @@
-{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../config/secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AAwCnD;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CACpB,IAAyB;IAEzB,kDAAkD;IAClD,6DAA6D;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,GAAG,EAAE;QACrB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,aAAa,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;IACvB,CAAC,CAAC;IAEF,SAAS,CAAC,QAAQ,GAAG,GAAG,EAAE;QACxB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,UAAU,IAAI,YAAY,CAAC;QACpC,CAAC;QACD,OAAO,UAAU,IAAI,cAAc,CAAC;IACtC,CAAC,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,OAAO,SAAoC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../config/secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AAwCnD;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CACpB,IAAyB;IAEzB,kDAAkD;IAClD,6DAA6D;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,GAAG,EAAE;QACrB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,4EAA4E;YAC5E,IACE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,KAAK,KAAK,OAAO,CAAC,aAAa,CAAC,KAAK,EACtE,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,aAAa,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;IACvB,CAAC,CAAC;IAEF,SAAS,CAAC,QAAQ,GAAG,GAAG,EAAE;QACxB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,UAAU,IAAI,YAAY,CAAC;QACpC,CAAC;QACD,OAAO,UAAU,IAAI,cAAc,CAAC;IACtC,CAAC,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,OAAO,SAAoC,CAAC;AAC9C,CAAC"}

package/dist/internal/runtime/napi/napi.cjs

@@ -1,5 +1,5 @@
 // The version of the runtime this JS bundle was generated for.
-const version = "v1.54.2";
+const version = "v1.55.0";
 
 // Load the native module.
 const nativeModulePath = process.env.ENCORE_RUNTIME_LIB;
@@ -17,6 +17,7 @@ const {
   BodyReader,
   Bucket,
   BucketObject,
+  CacheCluster,
   CloudProvider,
   Cursor,
   Decimal,
@@ -57,6 +58,7 @@ module.exports = {
   BodyReader,
   Bucket,
   BucketObject,
+  CacheCluster,
   CloudProvider,
   Cursor,
   Decimal,

package/dist/internal/runtime/napi/napi.d.cts

@@ -74,6 +74,119 @@ export interface BuildMeta {
   uncommittedChanges: boolean
 }
 
+/** A cache cluster for storing cached data. */
+export class CacheCluster {
+  /** Get a value by key. */
+  get(key: string, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Set a value by key with optional TTL. */
+  set(key: string, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<void>
+  /** Set a value only if the key doesn't exist. */
+  setIfNotExists(key: string, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<boolean>
+  /** Replace a value only if the key exists. */
+  replace(key: string, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<boolean>
+  /** Get old value and set new value atomically. */
+  getAndSet(key: string, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Get value and delete key atomically. */
+  getAndDelete(key: string, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Delete one or more keys. */
+  delete(keys: Array<string>, source?: Request | undefined | null): Promise<number>
+  /** Get multiple values. */
+  mget(keys: Array<string>, source?: Request | undefined | null): Promise<Array<Buffer | undefined | null>>
+  /** Append to a string value. */
+  append(key: string, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Get a substring of a string value. */
+  getRange(key: string, start: number, end: number, source?: Request | undefined | null): Promise<Buffer>
+  /** Set a substring at a specific offset. */
+  setRange(key: string, offset: number, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Get string length. */
+  strlen(key: string, source?: Request | undefined | null): Promise<number>
+  /** Increment an integer value. */
+  incrBy(key: string, delta: number, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Decrement an integer value. */
+  decrBy(key: string, delta: number, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Increment a float value. */
+  incrByFloat(key: string, delta: number, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Push values to the left (head) of a list. */
+  lpush(key: string, values: Array<Buffer>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Push values to the right (tail) of a list. */
+  rpush(key: string, values: Array<Buffer>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /**
+   * Pop a value from the left (head) of a list.
+   * Returns null if the list is empty or doesn't exist.
+   */
+  lpop(key: string, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<Buffer | null>
+  /**
+   * Pop a value from the right (tail) of a list.
+   * Returns null if the list is empty or doesn't exist.
+   */
+  rpop(key: string, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Get element at index from a list. */
+  lindex(key: string, index: number, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Get a range of elements from a list. */
+  lrange(key: string, start: number, stop: number, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Get all elements of a list (traced as "items"). */
+  lrangeAll(key: string, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Get list length. */
+  llen(key: string, source?: Request | undefined | null): Promise<number>
+  /** Trim a list to the specified range. */
+  ltrim(key: string, start: number, stop: number, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<void>
+  /** Set element at index in list. */
+  lset(key: string, index: number, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<void>
+  /** Insert value before pivot in list. */
+  linsertBefore(key: string, pivot: Buffer, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Insert value after pivot in list. */
+  linsertAfter(key: string, pivot: Buffer, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Remove elements from list. */
+  lremAll(key: string, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Remove elements from list. */
+  lremFirst(key: string, count: number, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Remove elements from list. */
+  lremLast(key: string, count: number, value: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Move element between lists atomically. */
+  lmove(src: string, dst: string, srcDir: string, dstDir: string, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Add members to a set. */
+  sadd(key: string, members: Array<Buffer>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Remove members from a set. */
+  srem(key: string, members: Array<Buffer>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Check if member exists in set. */
+  sismember(key: string, member: Buffer, source?: Request | undefined | null): Promise<boolean>
+  /** Get all members of a set. */
+  smembers(key: string, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Get set cardinality. */
+  scard(key: string, source?: Request | undefined | null): Promise<number>
+  /**
+   * Pop a single random member from a set.
+   * Returns null if the set is empty or doesn't exist.
+   */
+  spop(key: string, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<Buffer | null>
+  /** Pop random members from a set. */
+  spopN(key: string, count: number, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /**
+   * Get a single random member from a set (without removing).
+   * Returns null if the set is empty or doesn't exist.
+   */
+  srandmember(key: string, source?: Request | undefined | null): Promise<Buffer | null>
+  /**
+   * Get random members from a set (without removing).
+   * Positive count returns distinct elements, negative count may return duplicates.
+   */
+  srandmemberN(key: string, count: number, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Get the difference between sets. */
+  sdiff(keys: Array<string>, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Store the difference between sets. */
+  sdiffstore(destination: string, keys: Array<string>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Get the intersection of sets. */
+  sinter(keys: Array<string>, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Store the intersection of sets. */
+  sinterstore(destination: string, keys: Array<string>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Get the union of sets. */
+  sunion(keys: Array<string>, source?: Request | undefined | null): Promise<Array<Buffer>>
+  /** Store the union of sets. */
+  sunionstore(destination: string, keys: Array<string>, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<number>
+  /** Move member from one set to another. */
+  smove(src: string, dst: string, member: Buffer, ttlMs?: number | undefined | null, source?: Request | undefined | null): Promise<boolean>
+}
+
 /** CallOpts can be used to set options for API calls. */
 export interface CallOpts {
   authData?: PVals
@@ -279,6 +392,7 @@ export class Runtime {
   sqlDatabase(encoreName: string): SQLDatabase
   pubsubTopic(encoreName: string): PubSubTopic
   bucket(encoreName: string): Bucket
+  cacheCluster(encoreName: string): CacheCluster
   gateway(encoreName: string, cfg: GatewayConfig): Gateway
   /** Gets the root logger from the runtime */
   logger(): Logger
@@ -307,7 +421,6 @@ export class Runtime {
   createMetricsRegistry(buffer: object): void
   /** Get the shared metrics registry (all worker threads use this) */
   getMetricsRegistry(): MetricsRegistry
-
 }
 
 export interface RuntimeConfig {

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

@@ -0,0 +1,268 @@
+/// <reference types="node" />
+import { CacheCluster } from "./cluster.js";
+import { Keyspace, KeyspaceConfig, WriteOptions } from "./keyspace.js";
+/**
+ * Base class for basic (scalar value) keyspaces.
+ * Provides get/set/replace/etc operations.
+ * @internal
+ */
+declare abstract class BasicKeyspace<K, V> extends Keyspace<K> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    /**
+     * Serializes a value to a Buffer for storage.
+     */
+    protected abstract serialize(value: V): Buffer;
+    /**
+     * Deserializes a Buffer from storage to a value.
+     */
+    protected abstract deserialize(data: Buffer): V;
+    /**
+     * Gets the value stored at key.
+     * If the key does not exist, it returns `undefined`.
+     *
+     * @returns The value, or `undefined` if the key does not exist.
+     * @see https://redis.io/commands/get/
+     */
+    get(key: K): Promise<V | undefined>;
+    /**
+     * Gets the values stored at multiple keys.
+     *
+     * @returns An array of values in the same order as the provided keys.
+     * Each element is the value or `undefined` if the key was not found.
+     * @see https://redis.io/commands/mget/
+     */
+    multiGet(...keys: K[]): Promise<(V | undefined)[]>;
+    /**
+     * Updates the value stored at key to val.
+     *
+     * @see https://redis.io/commands/set/
+     */
+    set(key: K, value: V, options?: WriteOptions): Promise<void>;
+    /**
+     * Sets the value stored at key to val, but only if the key does not exist beforehand.
+     *
+     * @throws {CacheKeyExists} If the key already exists.
+     * @see https://redis.io/commands/setnx/
+     */
+    setIfNotExists(key: K, value: V, options?: WriteOptions): Promise<void>;
+    /**
+     * Replaces the existing value stored at key to val.
+     *
+     * @throws {CacheMiss} If the key does not already exist.
+     * @see https://redis.io/commands/set/
+     */
+    replace(key: K, value: V, options?: WriteOptions): Promise<void>;
+    /**
+     * Updates the value of key to val and returns the previously stored value.
+     * If the key does not already exist, it sets it and returns `undefined`.
+     *
+     * @returns The previous value, or `undefined` if the key did not exist.
+     * @see https://redis.io/commands/getset/
+     */
+    getAndSet(key: K, value: V, options?: WriteOptions): Promise<V | undefined>;
+    /**
+     * Deletes the key and returns the previously stored value.
+     * If the key does not already exist, it returns `undefined`.
+     *
+     * @returns The previous value, or `undefined` if the key did not exist.
+     * @see https://redis.io/commands/getdel/
+     */
+    getAndDelete(key: K): Promise<V | undefined>;
+}
+/**
+ * StringKeyspace stores string values.
+ *
+ * @example
+ * ```ts
+ * const tokens = new StringKeyspace<string>(cluster, {
+ *   keyPattern: "token/:id",
+ *   defaultExpiry: ExpireIn(3600000), // 1 hour
+ * });
+ *
+ * await tokens.set("abc123", "user-token-value");
+ * const token = await tokens.get("abc123");
+ * ```
+ */
+export declare class StringKeyspace<K> extends BasicKeyspace<K, string> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected serialize(value: string): Buffer;
+    protected deserialize(data: Buffer): string;
+    /**
+     * Appends a string to the value stored at key.
+     *
+     * If the key does not exist it is first created and set as the empty string,
+     * causing append to behave like set.
+     *
+     * @returns The new string length.
+     * @see https://redis.io/commands/append/
+     */
+    append(key: K, value: string, options?: WriteOptions): Promise<number>;
+    /**
+     * Returns a substring of the string value stored at key.
+     *
+     * The `start` and `end` values are zero-based indices, but unlike typical slicing
+     * the `end` value is inclusive.
+     *
+     * Negative values can be used in order to provide an offset starting
+     * from the end of the string, so -1 means the last character.
+     *
+     * If the string does not exist it returns the empty string.
+     *
+     * @param key - The cache key.
+     * @param start - Start index (inclusive, 0-based).
+     * @param end - End index (inclusive, 0-based). Use -1 for end of string.
+     * @returns The substring.
+     * @see https://redis.io/commands/getrange/
+     */
+    getRange(key: K, start: number, end: number): Promise<string>;
+    /**
+     * Overwrites part of the string stored at key, starting at
+     * the zero-based `offset` and for the entire length of `value`, extending
+     * the string if necessary.
+     *
+     * If the offset is larger than the current string length stored at key,
+     * the string is first padded with zero-bytes to make offset fit.
+     *
+     * Non-existing keys are considered as empty strings.
+     *
+     * @param key - The cache key.
+     * @param offset - Zero-based byte offset to start writing at.
+     * @param value - The string to write.
+     * @returns The length of the string after the operation.
+     * @see https://redis.io/commands/setrange/
+     */
+    setRange(key: K, offset: number, value: string, options?: WriteOptions): Promise<number>;
+    /**
+     * Returns the length of the string value stored at key.
+     *
+     * Non-existing keys are considered as empty strings.
+     *
+     * @returns The string length.
+     * @see https://redis.io/commands/strlen/
+     */
+    len(key: K): Promise<number>;
+}
+/**
+ * IntKeyspace stores 64-bit integer values.
+ * Values are floored to integers using `Math.floor`.
+ * For fractional values, use {@link FloatKeyspace} instead.
+ *
+ * @example
+ * ```ts
+ * const counters = new IntKeyspace<string>(cluster, {
+ *   keyPattern: "counter/:name",
+ * });
+ *
+ * await counters.set("page-views", 0);
+ * const newCount = await counters.increment("page-views", 1);
+ * ```
+ */
+export declare class IntKeyspace<K> extends BasicKeyspace<K, number> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected serialize(value: number): Buffer;
+    protected deserialize(data: Buffer): number;
+    /**
+     * Increments the number stored at key by `delta`.
+     *
+     * If the key does not exist it is first created with a value of 0
+     * before incrementing.
+     *
+     * Negative values can be used to decrease the value,
+     * but typically you want to use {@link decrement} for that.
+     *
+     * @param key - The cache key.
+     * @param delta - The amount to increment by (default 1).
+     * @returns The new value after incrementing.
+     * @see https://redis.io/commands/incrby/
+     */
+    increment(key: K, delta?: number, options?: WriteOptions): Promise<number>;
+    /**
+     * Decrements the number stored at key by `delta`.
+     *
+     * If the key does not exist it is first created with a value of 0
+     * before decrementing.
+     *
+     * Negative values can be used to increase the value,
+     * but typically you want to use {@link increment} for that.
+     *
+     * @param key - The cache key.
+     * @param delta - The amount to decrement by (default 1).
+     * @returns The new value after decrementing.
+     * @see https://redis.io/commands/decrby/
+     */
+    decrement(key: K, delta?: number, options?: WriteOptions): Promise<number>;
+}
+/**
+ * FloatKeyspace stores 64-bit floating point values.
+ *
+ * @example
+ * ```ts
+ * const scores = new FloatKeyspace<string>(cluster, {
+ *   keyPattern: "score/:playerId",
+ * });
+ *
+ * await scores.set("player1", 100.5);
+ * const newScore = await scores.increment("player1", 10.25);
+ * ```
+ */
+export declare class FloatKeyspace<K> extends BasicKeyspace<K, number> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected serialize(value: number): Buffer;
+    protected deserialize(data: Buffer): number;
+    /**
+     * Increments the number stored at key by `delta`.
+     *
+     * If the key does not exist it is first created with a value of 0
+     * before incrementing.
+     *
+     * Negative values can be used to decrease the value,
+     * but typically you want to use {@link decrement} for that.
+     *
+     * @param key - The cache key.
+     * @param delta - The amount to increment by (default 1).
+     * @returns The new value after incrementing.
+     * @see https://redis.io/commands/incrbyfloat/
+     */
+    increment(key: K, delta?: number, options?: WriteOptions): Promise<number>;
+    /**
+     * Decrements the number stored at key by `delta`.
+     *
+     * If the key does not exist it is first created with a value of 0
+     * before decrementing.
+     *
+     * Negative values can be used to increase the value,
+     * but typically you want to use {@link increment} for that.
+     *
+     * @param key - The cache key.
+     * @param delta - The amount to decrement by (default 1).
+     * @returns The new value after decrementing.
+     * @see https://redis.io/commands/incrbyfloat/
+     */
+    decrement(key: K, delta?: number, options?: WriteOptions): Promise<number>;
+}
+/**
+ * StructKeyspace stores arbitrary objects serialized as JSON.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const users = new StructKeyspace<string, User>(cluster, {
+ *   keyPattern: "user/:id",
+ *   defaultExpiry: ExpireIn(3600000),
+ * });
+ *
+ * await users.set("user1", { id: "user1", name: "Alice", email: "alice@example.com" });
+ * const user = await users.get("user1");
+ * ```
+ */
+export declare class StructKeyspace<K, V> extends BasicKeyspace<K, V> {
+    constructor(cluster: CacheCluster, config: KeyspaceConfig<K>);
+    protected serialize(value: V): Buffer;
+    protected deserialize(data: Buffer): V;
+}
+export {};