Method withCacheNullable

packages/cache/src/service.ts:285–314

* Cache wrapper for functions whose result may legitimately be `null`. * * Stores results in a marked envelope so cached nulls are distinct from misses. * * @param fn - Function to execute (and optionally cache); may return null. * @param key - Cache key * @param ttlMs - Time to li

(
    fn: () => Promise<T | null>,
    key: CacheKey,
    ttlMs: number
  )

   * @returns Cached value if present (including a cached `null`), otherwise fresh result from fn()
   */
  async withCacheNullable<T extends NonNullable<unknown>>(
    fn: () => Promise<T | null>,
    key: CacheKey,
    ttlMs: number
  ): Promise<T | null> {
    if (!this.canUseCache(key, ttlMs)) {
      return await fn();
    }

    const cachedValue = await this.tryGetCachedValue<unknown>(key, ttlMs);
    if (cachedValue !== undefined) {
      if (this.isNullableCacheBox<T>(cachedValue)) {
        return cachedValue.value;
      }

      logger.debug(
        { key, ttlMs },
        "Nullable cache entry is missing marker or value field; treating as cache miss and refreshing"
      );
    }

    const fresh = await fn();
    // Guard against type-erased callers resolving undefined.
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- types exclude undefined; this guards against type-erasure bugs
    if (fresh !== undefined) {
      const box: NullableCacheBox<T> = { [NULLABLE_BOX_MARKER]: true, value: fresh };
      await this.trySetCache(key, box, ttlMs);
    }
    return fresh;
  }

  /** Returns false when callers should bypass cache and execute directly. */
  private canUseCache(key: CacheKey, ttlMs: number): boolean {