auto-fetch-fifo-ttl-cache/src/auto-fetch-fifo-ttl-cache.interfaces.ts

An in-memory FIFO cache with fixed TTL for Node.js, designed to streamline the common get-or-fetch pattern by automating value retrieval. It uses an internal keyed lock to coalesce concurrent fetches for the same key, reducing redundant network calls and

/**
 * Copyright 2025 Ori Cohen https://github.com/ori88c
 * https://github.com/ori88c/auto-fetch-fifo-ttl-cache
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

export interface IAutoFetchFIFOCacheOptions<ValueType> {
  /**
   * The maximum number of key-value pairs allowed in the cache.
   */
  capacity: number;

  /**
   * The maximum duration (in milliseconds) after which an inserted key is considered
   * outdated and removed from the cache.
   */
  ttlMs: number;

  /**
   * A user-provided asynchronous function responsible for fetching a value when a key is not
   * found in the cache. This function is internally invoked by the `getOrFetch` method.
   *
   * ### ⚠️ Error Handling
   * If the fetcher throws or returns a rejected promise, the corresponding `getOrFetch` call
   * will also reject, and **no value will be cached** for the key. This behavior mirrors the
   * manual workflow of fetching a value before explicitly storing it via `set`, allowing
   * developers to retain full control over error-handling strategies.
   * The cache remains agnostic to how errors should be handled. If desired, the fetcher itself
   * may implement fallback logic - such as returning a default value or a sentinel object
   * representing failure - depending on the needs of the application.
   *
   * @param key The cache key whose value needs to be fetched.
   * @returns A promise resolving to the value associated with the given key.
   */
  fetchValue: (key: string) => Promise<ValueType>;
}