Copy page

Data Management

BackgroundLoader

The BackgroundLoader class provides asynchronous loading of configuration data while minimizing gateway latency. It's ideal for critical configuration that powers your gateway for smart routing or similar use cases.

The BackgroundLoader optimizes performance by:

• Immediately returning cached data when available
• Asynchronously refreshing data in the background
• Only blocking when cache is empty or expired

Constructor

Code
new BackgroundLoader<T>(
  loader: (key: string) => Promise<T>,
  options: BackgroundLoaderOptions
)

Creates a new background loader instance.

• loader - Asynchronous function that loads data for a given key
• options - Configuration options including TTL and timeout
• T - The type of data being loaded

Options

Code
interface BackgroundLoaderOptions {
  // (Required) Time to live for cache entries in seconds
  ttlSeconds: number;
  // (Optional) Timeout for the loader function in seconds
  loaderTimeoutSeconds?: number;
}

Methods

get

Retrieves data for the specified key. Returns immediately if cached, otherwise blocks while loading.

Code
get(key: string): Promise<T>

Example

Code
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
import { BackgroundLoader } from "@zuplo/runtime";

const loaderFunction = async (key: string) => {
  // Add error handling and validation as needed for your use case
  const result = await fetch(`https://example-config-service.com/${key}`);
  const data = await result.json();
  return data;
};

// Create an instance of the component at the module level
// Here with a cache expiry of 60s
//
const backgroundLoader = new BackgroundLoader(loaderFunction, {
  ttlSeconds: 60,
  loaderTimeoutSeconds: 10,
});

export default async function (request: ZuploRequest, context: ZuploContext) {
  // once an entry is cached this will return immediately. It will only block
  // if the cache is empty or has expired.
  const data = await backgroundLoader.get(request.params.loaderId);
  return data;
}

The BackgroundLoader will ensure that only one request per 'key' is active at any one time to avoid overloading your destination services.

The BackgroundLoader has the following options. In the above example, we set ttlSeconds:

Code
interface BackgroundLoaderOptions {
  // (Required) The time to live for the cache entry in seconds
  ttlSeconds: number;
  // (Optional) The timeout for the loader -- error out if the load takes longer than this. Useful to prevent hanging background requests.
  loaderTimeoutSeconds?: number;
}