@devvit/public-api 0.10.23-next-2024-06-28-567251747.0 → 0.10.23-next-2024-07-01-a6d03873c.0

package/devvit/internals/blocks/handler/ContextBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContextBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/ContextBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAY1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAiBxD,qBAAa,cAAc;IAClB,YAAY,CACjB,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,QAAQ,GACjB,MAAM,CAAC,OAAO;CA2ClB"}
+{"version":3,"file":"ContextBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/ContextBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAY1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQxD,qBAAa,cAAc;IAClB,YAAY,CACjB,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,QAAQ,GACjB,MAAM,CAAC,OAAO;CA2ClB"}

package/devvit/internals/blocks/handler/ContextBuilder.js

@@ -14,12 +14,7 @@ import { useChannel } from './useChannel.js';
 import { useForm } from './useForm.js';
 import { useInterval } from './useInterval.js';
 import { useState } from './useState.js';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const UnimplementedProxy = new Proxy({}, {
-    get: function (_target, prop, _receiver) {
-        throw new Error(`Unimplemented API: ${String(prop)}`);
-    },
-});
+import { makeCache } from './cache.js';
 export class ContextBuilder {
     buildContext(renderContext, request, metadata) {
         const modLog = new ModLogClient(metadata);
@@ -32,7 +27,7 @@ export class ContextBuilder {
         const media = new MediaClient(metadata);
         const assets = new AssetsClient();
         const realtime = new RealtimeClient(metadata);
-        const cache = UnimplementedProxy;
+        const cache = makeCache(redis, renderContext._state);
         const apiClients = {
             modLog,
             kvStore,

package/devvit/internals/blocks/handler/RenderContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/RenderContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/RenderContext.ts"],"names":[],"mappings":"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"}

package/devvit/internals/blocks/handler/RenderContext.js

@@ -49,19 +49,29 @@ export class RenderContext {
         this._undeliveredHandlers = {};
         this.request = request;
         this.meta = meta;
-        __classPrivateFieldSet(this, _RenderContext_state, request.state ?? {}, "f");
+        __classPrivateFieldSet(this, _RenderContext_state, request.state ?? {
+            __cache: {},
+        }, "f");
         this._rootProps = request.props ?? {};
     }
     /** The state delta new to this render. */
     get _changedState() {
-        const changed = {};
+        const changed = {
+            __cache: __classPrivateFieldGet(this, _RenderContext_state, "f").__cache ?? {},
+        };
         for (const key in this._changed)
             changed[key] = this._state[key];
         const unmounted = new Set(Object.keys(this._state));
         Object.keys(this._hooks).forEach((key) => {
+            if (key === '__cache') {
+                return;
+            }
             unmounted.delete(key);
         });
         unmounted.forEach((key) => {
+            if (key === '__cache') {
+                return;
+            }
             const t = { __deleted: true };
             this._state[key] = changed[key] = t;
         });

package/devvit/internals/blocks/handler/cache.d.ts

@@ -0,0 +1,9 @@
+import type { RedisClient } from '../../../../types/redis.js';
+import type { JSONValue } from '@devvit/shared-types/json.js';
+import type { CacheOptions, Clock, LocalCache } from './promise_cache.js';
+import type { RenderContext } from './RenderContext.js';
+export type CacheHelper = <T extends JSONValue>(fn: () => Promise<T>, options: CacheOptions) => Promise<T>;
+export declare function makeCache(redis: RedisClient, state: RenderContext['_state'] & {
+    __cache?: LocalCache;
+}, clock?: Clock): CacheHelper;
+//# sourceMappingURL=cache.d.ts.map

package/devvit/internals/blocks/handler/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,SAAS,EAC5C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,YAAY,KAClB,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,EACzD,KAAK,GAAE,KAAmB,GACzB,WAAW,CAGb"}

package/devvit/internals/blocks/handler/cache.js

@@ -0,0 +1,5 @@
+import { PromiseCache, SystemClock } from './promise_cache.js';
+export function makeCache(redis, state, clock = SystemClock) {
+    const pc = new PromiseCache(redis, state, clock);
+    return pc.cache.bind(pc);
+}

package/devvit/internals/blocks/handler/cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/cache.test.ts"],"names":[],"mappings":""}

package/devvit/internals/blocks/handler/promise_cache.d.ts

@@ -0,0 +1,67 @@
+import type { JSONValue, RedisClient } from '../../../../index.js';
+export type CacheEntry = {
+    value: JSONValue | null;
+    expires: number;
+    error: string | null;
+    errorTime: number | null;
+    checkedAt: number;
+    errorCount: number;
+};
+export type Clock = {
+    now(): Date;
+};
+export declare const SystemClock: Clock;
+export type CacheOptions = {
+    /**
+     * Time to live in milliseconds.
+     */
+    ttl: number;
+    /**
+     * Key to use for caching.
+     */
+    key: string;
+};
+export type LocalCache = {
+    [key: string]: CacheEntry;
+};
+export declare function _namespaced(key: string): string;
+export declare function _lock(key: string): string;
+export declare const retryLimit = 3;
+export declare const clientRetryDelay = 1000;
+export declare const allowStaleFor = 30000;
+type WithLocalCache = {
+    __cache?: LocalCache;
+};
+/**
+ * Refactored out into a class to allow for easier testing and clarity of purpose.
+ *
+ * This class is responsible for managing the caching of promises. It is a layered cache, meaning it will first check
+ * the local cache, then the redis cache, and finally the source of truth. It will also handle refreshing the cache according
+ * to the TTL and error handling.
+ *
+ * Please note that in order to prevent a stampede of requests to the source of truth, we use a lock in redis to ensure only one
+ * request is made to the source of truth at a time.  If the lock is obtained, the cache will be updated and the lock will be released.
+ *
+ * Additionally, we use a polling mechanism to fetch the cache if the lock is not obtained.  This is to prevent unnecessary errors.
+ *
+ * Finally, we also want to prevent stampedes against redis for the lock election and the retries.  We use a ramping probability to ease in the
+ * attempts to get the lock, and not every error will trigger a retry.
+ *
+ * This means that the cache will be eventually consistent, but will not be immediately consistent. This is a tradeoff we are willing to make.
+ * Additionally, this means that the TTL is not precice.  The cache may be updated a bit more often than the TTL, but it will not be updated less often.
+ *
+ */
+export declare class PromiseCache {
+    #private;
+    constructor(redis: RedisClient, state: WithLocalCache, clock?: Clock);
+    /**
+     * This is the public API for the cache.  Call this method to cache a promise.
+     *
+     * @param closure
+     * @param options
+     * @returns
+     */
+    cache<T extends JSONValue>(closure: () => Promise<T>, options: CacheOptions): Promise<T>;
+}
+export {};
+//# sourceMappingURL=promise_cache.d.ts.map

package/devvit/internals/blocks/handler/promise_cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise_cache.d.ts","sourceRoot":"","sources":["../../../../../src/devvit/internals/blocks/handler/promise_cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnE,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAClB,GAAG,IAAI,IAAI,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAIzB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,CAAC;AAEvD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzC;AAKD,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC,KAAK,cAAc,GAAG;IACpB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB,CAAC;AASF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;;gBAUX,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,GAAE,KAAmB;IAMjF;;;;;;OAMG;IACG,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC;CA6M/F"}

package/devvit/internals/blocks/handler/promise_cache.js

@@ -0,0 +1,239 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _PromiseCache_instances, _PromiseCache_redis, _PromiseCache_localCache, _PromiseCache_clock, _PromiseCache_state, _PromiseCache_localCachedAnswer, _PromiseCache_maybeRefreshCache, _PromiseCache_refreshCache, _PromiseCache_pollForCache, _PromiseCache_updateCache, _PromiseCache_calculateRamp, _PromiseCache_redisEntry, _PromiseCache_enforceTTL;
+export const SystemClock = {
+    now() {
+        return new Date();
+    },
+};
+export function _namespaced(key) {
+    return `__autocache__${key}`;
+}
+export function _lock(key) {
+    return `__lock__${key}`;
+}
+const pollEvery = 300; // milli
+const maxPollingTimeout = 1000; // milli
+const minTtlValue = 5000;
+export const retryLimit = 3;
+const errorRetryProbability = 0.1;
+export const clientRetryDelay = 1000;
+export const allowStaleFor = 30000;
+function _unwrap(entry) {
+    if (entry.error) {
+        throw new Error(entry.error);
+    }
+    return entry.value;
+}
+/**
+ * Refactored out into a class to allow for easier testing and clarity of purpose.
+ *
+ * This class is responsible for managing the caching of promises. It is a layered cache, meaning it will first check
+ * the local cache, then the redis cache, and finally the source of truth. It will also handle refreshing the cache according
+ * to the TTL and error handling.
+ *
+ * Please note that in order to prevent a stampede of requests to the source of truth, we use a lock in redis to ensure only one
+ * request is made to the source of truth at a time.  If the lock is obtained, the cache will be updated and the lock will be released.
+ *
+ * Additionally, we use a polling mechanism to fetch the cache if the lock is not obtained.  This is to prevent unnecessary errors.
+ *
+ * Finally, we also want to prevent stampedes against redis for the lock election and the retries.  We use a ramping probability to ease in the
+ * attempts to get the lock, and not every error will trigger a retry.
+ *
+ * This means that the cache will be eventually consistent, but will not be immediately consistent. This is a tradeoff we are willing to make.
+ * Additionally, this means that the TTL is not precice.  The cache may be updated a bit more often than the TTL, but it will not be updated less often.
+ *
+ */
+export class PromiseCache {
+    constructor(redis, state, clock = SystemClock) {
+        _PromiseCache_instances.add(this);
+        _PromiseCache_redis.set(this, void 0);
+        /**
+         * LocalCache is just an aliased reference to this.#state. Mutations to
+         * this object will also mutate this.#state
+         */
+        _PromiseCache_localCache.set(this, {});
+        _PromiseCache_clock.set(this, void 0);
+        _PromiseCache_state.set(this, void 0);
+        __classPrivateFieldSet(this, _PromiseCache_redis, redis, "f");
+        __classPrivateFieldSet(this, _PromiseCache_state, state, "f");
+        __classPrivateFieldSet(this, _PromiseCache_clock, clock, "f");
+    }
+    /**
+     * This is the public API for the cache.  Call this method to cache a promise.
+     *
+     * @param closure
+     * @param options
+     * @returns
+     */
+    async cache(closure, options) {
+        var _a;
+        (_a = __classPrivateFieldGet(this, _PromiseCache_state, "f")).__cache ?? (_a.__cache = {});
+        __classPrivateFieldSet(this, _PromiseCache_localCache, __classPrivateFieldGet(this, _PromiseCache_state, "f").__cache, "f");
+        __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_enforceTTL).call(this, options);
+        const localCachedAnswer = __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_localCachedAnswer).call(this, options.key);
+        if (localCachedAnswer !== undefined) {
+            return localCachedAnswer;
+        }
+        const existing = await __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_redisEntry).call(this, options.key);
+        const entry = await __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_maybeRefreshCache).call(this, options, existing, closure);
+        return _unwrap(entry);
+    }
+}
+_PromiseCache_redis = new WeakMap(), _PromiseCache_localCache = new WeakMap(), _PromiseCache_clock = new WeakMap(), _PromiseCache_state = new WeakMap(), _PromiseCache_instances = new WeakSet(), _PromiseCache_localCachedAnswer = function _PromiseCache_localCachedAnswer(key) {
+    const val = __classPrivateFieldGet(this, _PromiseCache_localCache, "f")[key];
+    if (val) {
+        const now = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime();
+        const hasRetryableError = val?.error &&
+            val?.errorTime &&
+            val.errorCount < retryLimit &&
+            Math.random() < errorRetryProbability &&
+            val.errorTime + clientRetryDelay < now;
+        const expired = val?.expires && val.expires < now && val.checkedAt + clientRetryDelay < now;
+        if (expired || hasRetryableError) {
+            delete __classPrivateFieldGet(this, _PromiseCache_localCache, "f")[key];
+            return undefined;
+        }
+        else {
+            return _unwrap(val);
+        }
+    }
+    return undefined;
+}, _PromiseCache_maybeRefreshCache = 
+/**
+ * If we've bothered to check redis, we're already on the backend.  Let's see if the cache either (1) contains an error, (2)
+ * is expired, (3) is missing, or (4) is about to expire.  If any of these are true, we'll refresh the cache based on heuristics.
+ *
+ * We'll always refresh if missing or expired, but its probabilistic if we'll refresh if about to expire or if we have an error.
+ */
+async function _PromiseCache_maybeRefreshCache(options, entry, closure) {
+    const expires = entry?.expires;
+    const rampProbability = expires ? __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_calculateRamp).call(this, expires) : 1;
+    if (!entry ||
+        (entry?.error && entry.errorCount < retryLimit && errorRetryProbability > Math.random()) ||
+        rampProbability > Math.random()) {
+        return __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_refreshCache).call(this, options, entry, closure);
+    }
+    else {
+        return entry;
+    }
+}, _PromiseCache_refreshCache = 
+/**
+ * The conditions for refreshing the cache are handled in the calling method, which should be
+ * #maybeRefreshCache.
+ *
+ * If you don't win the lock, you'll poll for the cache.  If you don't get the cache within maxPollingTimeout, you'll throw an error.
+ */
+async function _PromiseCache_refreshCache(options, entry, closure) {
+    const lockKey = _lock(options.key);
+    const now = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime();
+    /**
+     * The write lock should last for a while, but not the full TTL.  Hopefully write attempts settle down after a while.
+     */
+    const lockExpiration = new Date(now + options.ttl / 2);
+    const lockObtained = await __classPrivateFieldGet(this, _PromiseCache_redis, "f").set(lockKey, '1', {
+        expiration: lockExpiration,
+        nx: true,
+    });
+    if (lockObtained) {
+        return __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_updateCache).call(this, options.key, entry, closure, options.ttl);
+    }
+    else if (entry) {
+        // This entry is still valid, return it
+        return entry;
+    }
+    else {
+        const start = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now();
+        return __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_pollForCache).call(this, start, options.key, options.ttl);
+    }
+}, _PromiseCache_pollForCache = async function _PromiseCache_pollForCache(start, key, ttl) {
+    const pollingTimeout = Math.min(ttl, maxPollingTimeout);
+    const existing = await __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_redisEntry).call(this, key);
+    if (existing) {
+        return existing;
+    }
+    if (__classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime() - start.getTime() >= pollingTimeout) {
+        throw new Error(`Cache request timed out trying to get data at key: ${key}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollEvery));
+    return __classPrivateFieldGet(this, _PromiseCache_instances, "m", _PromiseCache_pollForCache).call(this, start, key, ttl);
+}, _PromiseCache_updateCache = 
+/**
+ * Actually update the cache.  This is the method that will be called if we have the lock.
+ */
+async function _PromiseCache_updateCache(key, entry, closure, ttl) {
+    const expires = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime() + ttl;
+    entry = entry ?? {
+        value: null,
+        expires,
+        errorCount: 0,
+        error: null,
+        errorTime: null,
+        checkedAt: 0,
+    };
+    try {
+        entry.value = await closure();
+        entry.error = null;
+        entry.errorCount = 0;
+        entry.errorTime = null;
+    }
+    catch (e) {
+        entry.value = null;
+        entry.error = e.message ?? 'Unknown error';
+        entry.errorTime = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime();
+        entry.errorCount++;
+    }
+    __classPrivateFieldGet(this, _PromiseCache_localCache, "f")[key] = entry;
+    await __classPrivateFieldGet(this, _PromiseCache_redis, "f").set(_namespaced(key), JSON.stringify(entry), {
+        expiration: new Date(expires + allowStaleFor),
+    });
+    /**
+     * Unlocking will allow retries to happen if there was an error.  Otherwise we don't unlock, because the lock
+     * will expire on its own.
+     */
+    if (entry.error && entry.errorCount < retryLimit) {
+        await __classPrivateFieldGet(this, _PromiseCache_redis, "f").del(_lock(key));
+    }
+    return entry;
+}, _PromiseCache_calculateRamp = function _PromiseCache_calculateRamp(expiry) {
+    const now = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime();
+    const remaining = expiry - now;
+    if (remaining < 0) {
+        return 1;
+    }
+    else if (remaining < 1000) {
+        return 0.1;
+    }
+    else if (remaining < 2000) {
+        return 0.01;
+    }
+    else if (remaining < 3000) {
+        return 0.001;
+    }
+    else {
+        return 0;
+    }
+}, _PromiseCache_redisEntry = async function _PromiseCache_redisEntry(key) {
+    const val = await __classPrivateFieldGet(this, _PromiseCache_redis, "f").get(_namespaced(key));
+    if (val) {
+        const entry = JSON.parse(val);
+        entry.checkedAt = __classPrivateFieldGet(this, _PromiseCache_clock, "f").now().getTime();
+        __classPrivateFieldGet(this, _PromiseCache_localCache, "f")[key] = entry;
+        return entry;
+    }
+    return undefined;
+}, _PromiseCache_enforceTTL = function _PromiseCache_enforceTTL(options) {
+    if (options.ttl < minTtlValue) {
+        console.warn(`Cache TTL cannot be less than ${minTtlValue} milliseconds! Updating ttl value of ${options.ttl} to ${minTtlValue}.`);
+        options.ttl = minTtlValue;
+    }
+};

package/meta.json

@@ -12191,7 +12191,7 @@
       "format": "esm"
     },
     "src/devvit/internals/blocks/handler/RenderContext.ts": {
-      "bytes": 6339,
+      "bytes": 6522,
       "imports": [
         {
           "path": "<runtime>",
@@ -12253,8 +12253,30 @@
       ],
       "format": "esm"
     },
+    "src/devvit/internals/blocks/handler/promise_cache.ts": {
+      "bytes": 9791,
+      "imports": [
+        {
+          "path": "<runtime>",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/devvit/internals/blocks/handler/cache.ts": {
+      "bytes": 676,
+      "imports": [
+        {
+          "path": "src/devvit/internals/blocks/handler/promise_cache.ts",
+          "kind": "import-statement",
+          "original": "./promise_cache.js"
+        }
+      ],
+      "format": "esm"
+    },
     "src/devvit/internals/blocks/handler/ContextBuilder.ts": {
-      "bytes": 3122,
+      "bytes": 2943,
       "imports": [
         {
           "path": "../shared-types/dist/Header.js",
@@ -12335,6 +12357,11 @@
           "path": "src/devvit/internals/blocks/handler/useState.ts",
           "kind": "import-statement",
           "original": "./useState.js"
+        },
+        {
+          "path": "src/devvit/internals/blocks/handler/cache.ts",
+          "kind": "import-statement",
+          "original": "./cache.js"
         }
       ],
       "format": "esm"
@@ -14274,7 +14301,7 @@
           "bytesInOutput": 5122
         },
         "src/devvit/internals/blocks/handler/RenderContext.ts": {
-          "bytesInOutput": 4721
+          "bytesInOutput": 4936
         },
         "src/devvit/internals/blocks/handler/useInterval.ts": {
           "bytesInOutput": 2357
@@ -14285,8 +14312,14 @@
         "src/devvit/internals/blocks/handler/useState.ts": {
           "bytesInOutput": 2314
         },
+        "src/devvit/internals/blocks/handler/promise_cache.ts": {
+          "bytesInOutput": 9074
+        },
+        "src/devvit/internals/blocks/handler/cache.ts": {
+          "bytesInOutput": 149
+        },
         "src/devvit/internals/blocks/handler/ContextBuilder.ts": {
-          "bytesInOutput": 1523
+          "bytesInOutput": 1362
         },
         "src/devvit/internals/ui-request-handler.ts": {
           "bytesInOutput": 618
@@ -14376,7 +14409,7 @@
           "bytesInOutput": 4450
         }
       },
-      "bytes": 14769344
+      "bytes": 14800351
     }
   }
 }

package/meta.min.json

@@ -3577,7 +3577,7 @@
       "format": "esm"
     },
     "src/devvit/internals/blocks/handler/RenderContext.ts": {
-      "bytes": 6339,
+      "bytes": 6522,
       "imports": [
         {
           "path": "<runtime>",
@@ -3639,8 +3639,30 @@
       ],
       "format": "esm"
     },
+    "src/devvit/internals/blocks/handler/promise_cache.ts": {
+      "bytes": 9791,
+      "imports": [
+        {
+          "path": "<runtime>",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/devvit/internals/blocks/handler/cache.ts": {
+      "bytes": 676,
+      "imports": [
+        {
+          "path": "src/devvit/internals/blocks/handler/promise_cache.ts",
+          "kind": "import-statement",
+          "original": "./promise_cache.js"
+        }
+      ],
+      "format": "esm"
+    },
     "src/devvit/internals/blocks/handler/ContextBuilder.ts": {
-      "bytes": 3122,
+      "bytes": 2943,
       "imports": [
         {
           "path": "../shared-types/dist/Header.js",
@@ -3721,6 +3743,11 @@
           "path": "src/devvit/internals/blocks/handler/useState.ts",
           "kind": "import-statement",
           "original": "./useState.js"
+        },
+        {
+          "path": "src/devvit/internals/blocks/handler/cache.ts",
+          "kind": "import-statement",
+          "original": "./cache.js"
         }
       ],
       "format": "esm"
@@ -4662,7 +4689,7 @@
       "imports": [],
       "exports": [],
       "inputs": {},
-      "bytes": 1151365
+      "bytes": 1167454
     },
     "dist/public-api.min.js": {
       "imports": [
@@ -5359,7 +5386,7 @@
           "bytesInOutput": 1184
         },
         "src/devvit/internals/blocks/handler/RenderContext.ts": {
-          "bytesInOutput": 2315
+          "bytesInOutput": 2394
         },
         "src/devvit/internals/blocks/handler/types.ts": {
           "bytesInOutput": 29
@@ -5367,8 +5394,14 @@
         "src/devvit/internals/blocks/handler/useState.ts": {
           "bytesInOutput": 1088
         },
+        "src/devvit/internals/blocks/handler/promise_cache.ts": {
+          "bytesInOutput": 2835
+        },
+        "src/devvit/internals/blocks/handler/cache.ts": {
+          "bytesInOutput": 65
+        },
         "src/devvit/internals/blocks/handler/ContextBuilder.ts": {
-          "bytesInOutput": 605
+          "bytesInOutput": 530
         },
         "src/apis/reddit/helpers/makeGettersEnumerable.ts": {
           "bytesInOutput": 166
@@ -5452,7 +5485,7 @@
           "bytesInOutput": 2135
         }
       },
-      "bytes": 245925
+      "bytes": 248829
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devvit/public-api",
-  "version": "0.10.23-next-2024-06-28-567251747.0",
+  "version": "0.10.23-next-2024-07-01-a6d03873c.0",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
@@ -30,8 +30,8 @@
   },
   "types": "./index.d.ts",
   "dependencies": {
-    "@devvit/protos": "0.10.23-next-2024-06-28-567251747.0",
-    "@devvit/shared-types": "0.10.23-next-2024-06-28-567251747.0",
+    "@devvit/protos": "0.10.23-next-2024-07-01-a6d03873c.0",
+    "@devvit/shared-types": "0.10.23-next-2024-07-01-a6d03873c.0",
     "base64-js": "1.5.1",
     "clone-deep": "4.0.1",
     "core-js": "3.27.2",
@@ -39,9 +39,9 @@
   },
   "devDependencies": {
     "@ampproject/filesize": "4.3.0",
-    "@devvit/eslint-config": "0.10.23-next-2024-06-28-567251747.0",
-    "@devvit/repo-tools": "0.10.23-next-2024-06-28-567251747.0",
-    "@devvit/tsconfig": "0.10.23-next-2024-06-28-567251747.0",
+    "@devvit/eslint-config": "0.10.23-next-2024-07-01-a6d03873c.0",
+    "@devvit/repo-tools": "0.10.23-next-2024-07-01-a6d03873c.0",
+    "@devvit/tsconfig": "0.10.23-next-2024-07-01-a6d03873c.0",
     "@microsoft/api-extractor": "7.41.0",
     "@reddit/faceplate-ui": "11.3.3",
     "@types/clone-deep": "4.0.1",
@@ -64,5 +64,5 @@
     }
   },
   "source": "./src/index.ts",
-  "gitHead": "57fef409f5bed1298d694999487c070f32fdfb37"
+  "gitHead": "6f1cebd8c39aba1a2b93e87377969e3de53edd1a"
 }